> ## Documentation Index
> Fetch the complete documentation index at: https://developer.vclasses.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# VClasses API Error Responses — Status Codes and Messages

> Complete reference for VClasses API error responses — HTTP status codes, JSON envelope shape, 403 message variants, and validation error field messages.

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:

```json theme={null}
{
  "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`:

```json theme={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

| Status | Meaning              | Common Causes                                                             |
| ------ | -------------------- | ------------------------------------------------------------------------- |
| 200    | OK                   | Request succeeded                                                         |
| 401    | Unauthorized         | Missing, invalid, or expired token                                        |
| 403    | Forbidden            | Valid token but insufficient role; quiz duration expired; course not paid |
| 404    | Not Found            | Resource ID doesn't exist; class has no assignment                        |
| 422    | Unprocessable Entity | Validation 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"`

<Note>
  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.
</Note>