Error codes

All errors come back as JSON with a stable shape:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Account has 12 credits, requested job needs 50",
    "type": "billing"
  }
}

HTTP status table

Status	Meaning	What to do
`400`	Bad request — invalid model id or missing parameter	Check `error.message`, fix payload
`401`	Missing or invalid `Authorization` header	Verify the `rlay_sk_...` token, regenerate if leaked
`402`	Insufficient credits	Top up at `/dashboard/billing`
`403`	Key revoked or account suspended	Contact support
`404`	Job not found, or wrong account ownership	Confirm `jobId` belongs to this key
`429`	Rate limit exceeded	Back off — see header `Retry-After`
`5xx`	Upstream provider error or routing failure	Retry with exponential backoff; we auto-failover internally

Error codes you'll actually see

Best practices

Always inspect error.code programmatically — error.message may change.
Treat 5xx as retryable, 4xx as not (except 429).
For async jobs, a failed status comes back via GET /v1/jobs/{id} — you won't get an HTTP 5xx for that path.

Quickstart→

Back to basics

Generate videos→

Async pattern reference

All errors come back as JSON with a stable shape:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Account has 12 credits, requested job needs 50",
    "type": "billing"
  }
}

HTTP status table

Status	Meaning	What to do
`400`	Bad request — invalid model id or missing parameter	Check `error.message`, fix payload
`401`	Missing or invalid `Authorization` header	Verify the `rlay_sk_...` token, regenerate if leaked
`402`	Insufficient credits	Top up at `/dashboard/billing`
`403`	Key revoked or account suspended	Contact support
`404`	Job not found, or wrong account ownership	Confirm `jobId` belongs to this key
`429`	Rate limit exceeded	Back off — see header `Retry-After`
`5xx`	Upstream provider error or routing failure	Retry with exponential backoff; we auto-failover internally

Error codes you'll actually see

Best practices

Always inspect error.code programmatically — error.message may change.
Treat 5xx as retryable, 4xx as not (except 429).
For async jobs, a failed status comes back via GET /v1/jobs/{id} — you won't get an HTTP 5xx for that path.

Quickstart→

Back to basics

Generate videos→

Async pattern reference

HTTP status table

Error codes you'll actually see

Best practices

Table of Contents

Error codes

HTTP status table

Error codes you'll actually see

Best practices

Table of Contents

Error codes

HTTP status table

Error codes you'll actually see

insufficient_credits (402)

model_not_found (400)

invalid_api_key (401)

rate_limit_exceeded (429)

upstream_error (5xx)

Best practices

Table of Contents

Error codes

HTTP status table

Error codes you'll actually see

insufficient_credits (402)

model_not_found (400)

invalid_api_key (401)

rate_limit_exceeded (429)

upstream_error (5xx)

Best practices

Table of Contents