Errors
Errors
Was this page helpful?
Handle stable HTTP statuses and machine-readable error codes without exposing secrets or raw internal failures.
HTTP status codes
- 400
- Malformed JSON or invalid full-render body
- 401
- Missing, invalid, or revoked key
- 402
- Insufficient credits
- 404
- Model or owned job not found
- 409
- Price lock changed or idempotency key conflict
- 422
- Generation field validation failed
- 429
- Rate limit exceeded; read Retry-After
- 502
- Generation or status service unavailable
- 503
- Catalog or rate limiter temporarily unavailable
- 504
- Start timed out; retry with the same idempotency key and body
Error envelope
Every endpoint except the five listed below returns this shape on error.
JSON example
{
"error": {
"code": "validation_error",
"message": "Request validation failed",
"details": [
{
"field": "durationSec",
"message": "Duration is not available for this model.",
"code": "invalid_choice"
}
]
},
"docs": "/docs/api"
}Legacy envelope (render, characters, media-search)
POST /api/v1/render's own key check, and every response from GET/POST /api/v1/characters, GET/DELETE /api/v1/characters/{id}, and POST /api/v1/media-search, use this older shape instead: an ok: false flag, a short string error code, an optional human-readable message or detail, and the same docs field.
JSON example
{
"ok": false,
"error": "invalid_body",
"message": "name: Required",
"docs": "https://reviral.ai/api/v1/render"
}Operational updates
Check API status before escalating a temporary 502 or 503.