Errors

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:

{
  "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)
`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
`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

{
  "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

{
  "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:

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

Get Started

Endpoints

Reference

HTTP status codes and `code` values

Example: plan limit reached

Example: a job failure

Example: request validation failure

​HTTP status codes and code values

​Example: plan limit reached

​Example: a job failure

​Example: request validation failure

HTTP status codes and `code` values

Example: plan limit reached

Example: a job failure

Example: request validation failure