Skip to main content
The VClasses API uses standard HTTP status codes and a consistent JSON error envelope for all non-2xx responses. When your request fails, parse the response body to find a human-readable message and, for validation errors, a field-level errors object that tells you exactly what to fix.

​
Error Envelope Shape

All error responses share the same top-level structure: 
{
  "message": "Human-readable error description",
  "errors": null
}

​
Validation Errors (422)

When a request fails validation, errors is populated with a bag of field-level messages rather than null: 
{
  "message": "ValidationError",
  "errors": {
    "rating": ["The rating field is required."]
  }
}
Each key in errors corresponds to an invalid field, and its value is an array of one or more error strings describing the problem with that field.

​
Status Code Reference

StatusMeaningCommon Causes
200OKRequest succeeded
401UnauthorizedMissing, invalid, or expired token
403ForbiddenValid token but insufficient role; quiz duration expired; course not paid
404Not FoundResource ID doesn’t exist; class has no assignment
422Unprocessable EntityValidation failed (missing or invalid fields)

​
Common 422 Validation Messages

When the API returns a 422, the errors object contains field-level messages. The following messages appear across homework and quiz grading endpoints:
  • "The rating field is required." — you omitted the rating field entirely.
  • "The rating must be an integer." — rating was provided but is not a whole number.
  • "The rating must be between 1 and 10." — rating is a number outside the allowed range.
  • "The comment may not be greater than 1000 characters." — your comment string exceeds the maximum length.
  • "The file must be a file of type: pdf." — the uploaded file is not a valid PDF.
  • "The grade field is required." — you omitted the grade field on a grading endpoint that requires it.

​
403 Message Variations

When the API returns a 403, the message field identifies the specific reason access was denied:
  • "Unauthorized Access" — your token is valid but your account lacks the required role for this endpoint.
  • "QuizDurationExpired" — the allowed time window for the quiz has passed.
  • "PayFirstToAccessTheCourse" — access to this resource requires an active course payment.

​
404 Message Variations

Different endpoints return different message strings when a resource is not found. Use these to distinguish which resource is missing:
  • Homework — "PDF Homework not found"
  • Quiz — "Not Found"
Non-numeric IDs in URL paths — for example, /api/v3/admin/homeworks/abc — are rejected at the router level before they reach application logic. The router returns a standard HTTP 404 response in this case, not the JSON error envelope described above. Your error-handling code should treat any 404 without a JSON body as a malformed URL rather than a missing resource.