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

# Errors

> One consistent error envelope, whether it's an SDK failure, a bad request, or a rate limit.

Every error -- from FastAPI's own request validation, an auth/role check, a rate limit, or a failure deep inside the SDK -- is normalized into the same JSON shape:

```json theme={null}
{
  "status": "error",
  "code": "invalid_config",
  "error": "Human-readable message",
  "request_id": "a1b2c3d4e5f6"
}
```

`request_id` also comes back as the `X-Request-ID` response header (and is accepted as a request header too, so a caller can supply their own correlation id). It's the same id this server logs the request under -- grep the logs for it to find exactly what happened server-side.

## HTTP status codes and `code` values

| HTTP status | `code`                                                                                             | Typical cause                                                                                                     |
| ----------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `400`       | `bad_request`, `model_load_error`, `sdk_error`                                                     | Model file missing, ONNX load failed, generic bad input                                                           |
| `401`       | `unauthorized`                                                                                     | Missing/invalid Bearer token, or a session token that isn't valid                                                 |
| `402`       | `plan_limit_reached`                                                                               | The free-plan run limit was reached; upgrade on the platform (raised as `PlanLimitError` in the SDK)              |
| `403`       | `forbidden`                                                                                        | Valid session, but the account's role doesn't allow this action (see [Authentication](/api/authentication))       |
| `404`       | `not_found`, `unknown_action`                                                                      | Unknown job/key/rule/deployment/invite id, or an unrecognized `action`                                            |
| `409`       | `conflict`                                                                                         | E.g. trying to demote the platform's last remaining Admin, or a duplicate email on registration                   |
| `422`       | `invalid_request`, `invalid_config`, `missing_field`, `calibration_required`, `unsupported_config` | Request failed validation, or a config/action combination the SDK can't run (e.g. QAT without `calibration_data`) |
| `424`       | `backend_not_installed`                                                                            | An optional export backend (TensorFlow, Paddle, TFLite) isn't installed                                           |
| `429`       | `rate_limited`                                                                                     | Too many requests from this caller -- see [Rate limiting](/api/rate-limiting)                                     |
| `500`       | `quantization_failed`, `benchmark_failed`, `internal_error`                                        | The job itself failed, or an unhandled bug in the API layer                                                       |
| `503`       | `unavailable`                                                                                      | E.g. the dashboard's site-password check when `R3AL_API_KEY` isn't configured server-side                         |

## Example: plan limit reached

```json theme={null}
{
  "status": "error",
  "code": "plan_limit_reached",
  "error": "Free plan run limit reached. Upgrade your plan at platform.r3al.ai.",
  "request_id": "a1b2c3d4e5f6"
}
```

## Example: a job failure

```json theme={null}
{
  "status": "error",
  "code": "calibration_required",
  "error": "QAT (action='qat_pipeline') requires calibration_data (training images).",
  "type": "UnsupportedConfigError",
  "request_id": "a1b2c3d4e5f6"
}
```

## Example: request validation failure

FastAPI's own body/query validation (wrong type, missing required field at the HTTP layer) includes a `details` array with the exact validation errors:

```json theme={null}
{
  "status": "error",
  "code": "invalid_request",
  "error": "Request body/query parameters failed validation",
  "details": [
    { "type": "missing", "loc": ["body", "model"], "msg": "Field required" }
  ],
  "request_id": "a1b2c3d4e5f6"
}
```