AI Gateway Errors

Both planes return a structured errors array. The inference plane additionally wraps it in the envelope the calling SDK expects, so OpenAI and Anthropic SDK exceptions work unchanged while the Telnyx detail remains available.

Error envelopes

{
  "errors": [
    {
      "code": "precondition_failed",
      "title": "Stale If-Match",
      "detail": "The resource version has changed; read it again.",
      "meta": { "current_version": 4 }
    }
  ]
}

{
  "error": {
    "message": "Send either max_tokens or max_completion_tokens, not both.",
    "type": "invalid_request_error",
    "param": "max_completion_tokens",
    "code": "invalid_request"
  },
  "errors": [
    {
      "code": "invalid_request",
      "title": "Invalid request",
      "detail": "Send either max_tokens or max_completion_tokens, not both.",
      "meta": {}
    }
  ]
}

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Model is not available to this token key."
  },
  "request_id": "0b1c2d3e-4f50-4617-8a29-3b4c5d6e7f80",
  "errors": [
    {
      "code": "model_not_in_catalog",
      "title": "Model not allowed",
      "detail": "Model is not available to this token key.",
      "meta": { "scope": "token_key" }
    }
  ]
}

Every response carries an X-Request-ID header. Keep it, together with the code, when reporting a problem. Do not log authorization headers, token keys or full request objects. An error that occurs after a streaming response has started cannot change the HTTP status. On the OpenAI surface it arrives as an error chunk; on the Anthropic surface, as an event: error frame. Consume every stream to completion and handle the SDK’s stream exceptions. A buffered-response delivery failure after JSON headers have been sent aborts the incomplete HTTP response; treat it as a transport failure with potentially completed provider work.

Additional request errors

HTTP status	Code	Handling
`400`	`invalid_metadata`	Correct the request-tag header; the error does not echo it.
`400`	`request_exceeds_tpm_limit`	The reservation exceeds an entire key, user or group TPM limit. Set an explicit output limit, reduce input or planned attempts, or ask the policy owner to adjust the limit. No provider dispatch or `Retry-After`; do not retry unchanged.
`400`	`context_length_exceeded`	Reduce input and/or requested output. No retry or fallback is attempted for this context rejection.
`413`	`request_too_large`	Reduce the serialized JSON body to the model’s advertised byte envelope.
`429`	`concurrency_limit_exceeded`	The key or group is at its concurrent-request cap. Inspect `errors[0].meta.scope` and retry with bounded backoff after `Retry-After`.
`504`	`upstream_timeout`	A provider attempt or the server-side request lifetime timed out before the client response started. Buffered requests can time out while reading the provider body. Usage may be unknown; a new request can incur additional work.
`409`	`cursor_expired`	Restart usage export within its retained time window and deduplicate by record ID. Waiting does not repair the cursor.

Pending provisioning

An inference response with HTTP 503, code enforcement_unavailable and the optional header x-ltg-enforcement-reason: provisioning indicates that the request encountered pending provisioning of the token key or its group/user policy. The header does not change the status or error body, and does not guarantee when provisioning will complete. If the header is absent, the provisioning state is unspecified. Retry model discovery with bounded backoff, respecting Retry-After, before sending the first inference request. Stop and surface the failure if provisioning exceeds your application’s deadline. Do not repeatedly create replacement keys or automatically replay inference requests.

Status codes

Status	Meaning	Action
`400`	A guardrail policy blocked the prompt or response; invalid body, unsupported option or model-specific option, unknown field, request over the size limits, token key limit out of range, invalid date or page parameter.	Correct the request.
`401`	Missing or wrong credential for this plane.	Use a Telnyx API key on the management plane and an `ltg_sk_` token key on the inference plane.
`403`	Blocked, revoked or expired key; blocked resource; model not allowed; budget or end-user policy denied.	Read the `code`. Do not treat `403` as retryable.
`404`	Resource does not exist or belongs to another account.	Check the ID.
`405`	Method not allowed, for example `PATCH` on a provider key.	Provider keys cannot be edited; create a new one instead.
`409`	Idempotency conflict, membership conflict or pagination snapshot conflict.	Read the `code`.
`412`	Stale `If-Match`.	Read the resource and retry with the current ETag.
`428`	Missing `If-Match` (or `If-None-Match: *` on end-user create).	Add the precondition header.
`429`	Rate limit exceeded.	Wait for `Retry-After`. Remember that inference retries are not idempotent.
`502`	The model provider failed.	Fail closed. The request may or may not have consumed provider work.
`503`	Enforcement, catalog, policy propagation or a required dependency is unavailable; a BYOK model lacks an attached provider key; or a spend report exceeds its capacity limit.	Fail closed. For an oversized spend report, narrow the dates or resource filters before retrying. Do not switch credentials or bypass the gateway.

Error codes

Code	Status	Meaning
`invalid_request`	400	Malformed or unsupported request, including a request over the size limits and a request to `/v1/messages` with a model that is not an Anthropic BYOK model (use `/v1/chat/completions` for those).
`prompt_blocked`	400	The group guardrail policy blocked the prompt before provider dispatch or budget reservation.
`response_blocked`	400, or SSE error after HTTP 200	The group guardrail policy withheld the generated response. Provider usage still applies. See Guardrails.
`limit_out_of_range`	400	A token key `max_budget`, `rpm_limit` or `tpm_limit` is 0 or above its maximum. See Token key limits.
`invalid_token_key`	401	The inference credential is missing, malformed or unknown.
`unauthorized`	401 / 403	The credential is not valid for this plane or resource.
`token_key_blocked`	403	The key is blocked, revoked or expired.
`resource_blocked`	403	The key’s user, group or asserted end user is blocked.
`budget_exceeded`	403	A key, user or group budget lacks headroom for the request’s reservation.
`end_user_budget_exceeded`	403	The asserted end user’s budget lacks headroom.
`model_not_in_catalog`	403	The model is not in the key’s or group’s allowlist.
`rate_limit_exceeded`	429	An RPM or TPM limit was hit.
`not_found`	404	No such resource in this account.
`conflict`	409	Membership or pagination snapshot conflict.
`idempotency_conflict`	409	The `Idempotency-Key` was reused with a different body, or the original request is still in progress.
`precondition_failed`	412	`If-Match` does not match the current version.
`precondition_required`	428	A required precondition header is missing.
`enforcement_unavailable`	503	Policy, catalog or a required dependency is unavailable; a BYOK model lacks an attached provider key; or a spend report exceeds the report limits.
`upstream_error`	502	The model provider returned an error.

Handling guidance

Never resolve an error by escalating credentials. A Telnyx API key, provider secret or any other credential is rejected on the inference plane by design.
Retry management mutations with the same idempotency key. A new key on retry can create a duplicate resource.
Do not automatically retry inference. A timeout or 502 is not proof that no provider work happened. Retry only errors that occurred before dispatch, and honor Retry-After on 429.
Re-read before re-writing. On 412, fetch the resource, review the change that landed, and apply your update to the current version.
Fail closed on 503. For inference, the old policy may no longer apply; do not assume the request is authorized. For a BYOK model, check that the group has a provider key attached for that model’s provider.
Narrow oversized spend reports before retrying. Reports exceeding 10,000 matching requests return 503 with enforcement_unavailable. Reduce the date range or narrow resource filters; reducing page size or retrying the unchanged query does not resolve this limit. Treat a failed report as unavailable, not zero usage.

AI Gateway

API

Concepts

For AI Agents

AI Gateway Errors

Error envelopes

Additional request errors

Pending provisioning

Status codes

Error codes

Handling guidance

​Error envelopes

​Additional request errors

​Pending provisioning

​Status codes

​Error codes

​Handling guidance

Error envelopes

Additional request errors

Pending provisioning

Status codes

Error codes

Handling guidance