Error codes

The table below is auto-generated from beatra's public runtime error taxonomy.

Every public beatra error response uses the standard error envelope. The error.code field is one of the stable public values below; the error.retryable boolean tells the client SDK whether a naive retry could succeed.

Branching rules for client SDKs

retryable: true errors can be retried with the exact same request after a brief backoff. If a Retry-After header is present, honor it.
retryable: false errors will produce the same outcome on retry; the client must either change the request, fix credentials, or surface the error to the user.
error.param (when present) is a JSON Pointer (RFC 6901) to the offending field in the request body.

Auth / Account

code	HTTP	retryable	description
`unauthorized`	401	no	Missing `Authorization` header.
`invalid_api_key`	401	no	API key not found, signature mismatch, disabled, or revoked.
`api_key_region_mismatch`	400	no	API key's region prefix doesn't match the endpoint host.
`tenant_disabled`	403	no	Tenant has been suspended.
`forbidden`	403	no	Generic permission denial.
`email_send_failed`	502	yes	Login-code email could not be delivered (transient send failure). Retryable after a brief backoff.

Billing

code	HTTP	retryable	description
`insufficient_balance`	402	no	Account balance is too low to create new work.
`billing_failed`	500	yes	Charge or refund attempt failed after retries.

Request validation

code	HTTP	retryable	description
`invalid_request`	422	no	Request body fails structural validation. `details.errors` lists field paths.
`unsupported_capability`	400	no	Capability does not exist or is disabled.
`unsupported_model`	400	no	Model does not exist or is not available for this capability.
`unsupported_option`	422	no	The selected model does not support a field in the request. `details.unsupported_fields[]` lists the field names. Use a different model or remove the field. In `auto` mode this is returned only when no available candidate can satisfy the requested options.
`safety_rejected`	400	no	Input prompt triggered safety policy. `details.policy_category` may be one of `violence` / `sexual` / `pii` / etc.
`content_filtered`	502	no	A safety filter blocked the output mid-generation. Try rephrasing the prompt or switching to a less strict model.
`not_found`	404	no	Requested HTTP resource or API endpoint was not found.
`http_error`	400	no	Generic HTTP error without a more specific public code.

Idempotency and response mode

code	HTTP	retryable	description
`idempotency_conflict`	409	no	Same `Idempotency-Key` was used previously with a different request body. Use a new key for a changed request.
`request_in_progress`	409	yes	Same `Idempotency-Key` matches an in-flight request. Retry later with the same key; the same response will be returned when available.
`streaming_not_yet_implemented`	501	no	Legacy compatibility code for older deployments where `stream=true` was recognized but not enabled. Current `/v1/chat/completions` supports streaming responses.

Capacity and availability

code	HTTP	retryable	description
`rate_limited`	429	yes	Caller-side rate limit exceeded. Retry with backoff.
`model_unavailable`	503	yes	The requested model is temporarily unavailable. Retryable; if persistent, switch model or contact support.
`model_request_failed`	502	yes	The model request failed after retryable service errors. Retry with backoff.
`model_timeout`	504	yes	The model request timed out. Retry with backoff.
`model_rate_limited`	429	yes	Model capacity was rate-limited. Retry with backoff.
`internal_error`	500	yes	Unclassified server-side error. Retryable.

Generated from 25 public runtime error codes. 13 internal or planned-surface runtime codes are intentionally omitted from public docs.

How to handle errors

Every error body is:

{
  "error": {
    "code": "<machine code>",
    "message": "<human description>",
    "retryable": true,
    "request_id": "req_..."
  }
}

retryable: true -> the same request can be retried after a brief backoff. If a Retry-After header is present, honor it.
retryable: false -> change the request before retrying. Looping on a non-retryable error is a bug.