Error Format & Rate Limits

Core inference APIs such as Chat use the OpenAI-compatible envelope below. Messages may return Anthropic-shaped errors (type: "error"); errors after a stream starts arrive in SSE data.

json

{
  "error": {
    "message": "Incorrect API key provided. ...",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Status	type / code	Meaning
400	`invalid_request_error`	Invalid parameter / context length exceeded (do not retry)
401	`authentication_error` / `missing_api_key` · `invalid_api_key`	Key missing, wrong, or expired
402	`insufficient_quota_error` / `insufficient_quota` · `spend_limit_exceeded`	Insufficient credit or spend limit reached
403	`permission_error` / `model_not_allowed` · `insufficient_scope`	Restricted by the key's allowed models or scopes
404	`invalid_request_error` / `model_not_found` · `job_not_found`	Model or job does not exist
413	`invalid_request_error`	Request body too large — see body limits
429	`rate_limit_error` / `rate_limit_exceeded`	Rate limit — retry after the `Retry-After` header
502	`api_error` / `backend_unavailable`	Upstream provider failure (retryable)

Rate limits

The default rate limit is 100 req/min per key, and you can adjust it when you create or edit the key. Check your remaining quota with the X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset response headers.

Auth endpoints (login, signup, and so on) have a separate, lower limit.

Retry decisions

Resolve input, authentication, credits, or access-policy issues before retrying 400, 401, 402, or 403.
For 429, wait the number of seconds in Retry-After. X-RateLimit-Reset is a Unix timestamp in milliseconds.
A 502 or 503 may be temporary. Increase the delay between retries and check whether the operation already ran.
409 idempotency_in_progress means the same request is still processing. Wait rather than resubmitting with a new key.
409 idempotency_key_reused means a different body was sent with the same key.
409 idempotency_response_not_replayable means an accepted stream or large response cannot be replayed.

Log x-request-id, HTTP status, and error.code to help trace failures. Video POSTs do not support Idempotency-Key; resubmitting after a lost response can create duplicate jobs. See idempotency scope and video polling.