Errors
Keiro returns HTTP errors in the dialect of the surface you called: the Chat Completions and Responses endpoints use the OpenAI-compatible shape shown below, and the Messages endpoint wraps the same content in the Anthropic envelope ({"type": "error", "error": {"type": ..., "message": ...}}), matching its streaming error events. The message, code, and details fields are the same across surfaces for the same failure. Field names and paths follow each surface's own spelling, and the Messages endpoint uses its own wording for a context overflow (see Context overflow details). Handle errors by status code and retry only where it is safe for your workload.
On this page 1 of 61
Handle status codes#
| Status | Meaning | Retry |
|---|---|---|
400 | Invalid request or unsupported parameter | No |
401 | Missing or invalid API key | No |
403 | Authenticated but not allowed | No |
404 | Route or model not found | No |
405 | Endpoint does not accept this method; Allow lists the ones it does | No |
408 | Request body stopped arriving | Yes, after delay |
409 | Conflicting request (idempotency reuse, capability conflict) | No |
413 | Request body too large | No |
415 | Request body must be uncompressed application/json | No |
429 | Rate limit or spend cap | Varies by code; honor x-should-retry and retryable |
500 | Internal error | Yes, with backoff |
502 | Upstream dependency failure | Yes, with backoff |
503 | Service or capacity unavailable | Yes, with backoff |
504 | Gateway deadline exceeded | Yes, with backoff |
Read the error body#
Error bodies follow an OpenAI-compatible shape when the failure can be classified safely. Treat message text as diagnostic context, not as a stable machine contract.
{
"error": {
"message": "Model 'eb1-frontier-preview' is not available for your account.",
"type": "forbidden",
"param": null,
"code": "model_not_available",
"request_id": "req_9f2c41d0",
"retryable": false
}
}
Match on code and type for machine handling. param is null unless the failing parameter is known, in which case it names the offending field. request_id is the same correlation id as the X-Request-Id response header, and retryable says whether an unchanged retry can succeed (see Rate and spend limits for the matching x-should-retry and retry-after-ms headers).
For 409 idempotency conflicts, the response includes code idempotency_key_conflict, and an X-Original-Request-Id header naming the original request when Keiro knows it. See Idempotency.
Limit and failure codes#
The gateway classifies limit denials and upstream failures into a fixed set of machine-readable codes. Match on code and type; when several rows share a code, details.dimension usually distinguishes them. The exception is one pair: a spend-cap denial and an upstream-provider passthrough both use code rate_limit_exceeded with no dimension. Until the legacy details.scope key is retired (see Error details below), tell those two apart by that key -- a spend-cap denial carries details.scope spend, while an upstream passthrough carries no scope.
code | type | Status | Retriable | details.dimension | Meaning |
|---|---|---|---|---|---|
rate_limit_exceeded | rate_limit_error | 429 | Yes | requests | Requests-per-minute limit for your organization was exceeded. |
rate_limit_exceeded | rate_limit_error | 429 | Yes | tokens | Tokens-per-minute limit for your organization was exceeded. |
rate_limit_exceeded | rate_limit_error | 429 | Yes | concurrency | Concurrent-request limit for your organization was exceeded. |
rate_limit_exceeded | rate_limit_error | 429 | No | token_budget | A per-request token budget from your plan was exceeded. |
request_exceeds_capacity | invalid_request_error | 400 | No | token_budget_request | The request's token estimate exceeds a full window of your plan's budget; it cannot succeed as sent. Reduce the input or max_output_tokens, or raise the limit. |
rate_limit_exceeded | rate_limit_error | 429 | Yes | — | A configured spend cap for your organization was reached. |
rate_limit_exceeded | rate_limit_error | 429 | Yes | spend_daily | A daily (UTC) spend cap was reached or would be exceeded. Retriable only when running requests hold the rest of the cap; see error.retryable. |
rate_limit_exceeded | rate_limit_error | 429 | Yes | spend_monthly | A monthly (UTC) spend cap was reached or would be exceeded. Retriable only when running requests hold the rest of the cap; see error.retryable. |
rate_limit_exceeded | rate_limit_error | 429 | No | spend_request | The request's estimated cost exceeds a per-request spend cap; it cannot succeed as sent. |
platform_pressure | rate_limit_error | 429 | Yes | — | Request rate was temporarily reduced by platform load; retry later. |
capacity_exceeded | rate_limit_error | 429 | Yes | capacity | Shared upstream capacity is exhausted; retry after the interval. |
rate_limit_exceeded | rate_limit_error | 429 | Yes | — | An upstream rate limit was hit; retry after the indicated period. |
no_capacity | server_error | 503 | Yes | — | No capacity is available for the requested model; retry shortly. |
connection_limit | server_error | 503 | Yes | — | The gateway is temporarily at connection capacity; retry after the interval. |
gateway_timeout | server_error | 504 | Yes | — | The request stopped making progress and was cancelled; a retry may succeed. |
gateway_restarting | server_error | 503 | Yes | — | The service restarted while the request was running; retry the request. |
upstream_server_error | api_error | 502 | Yes | — | An upstream dependency failed; the request may succeed on retry. |
provider_unavailable | api_error | 503 | Yes | — | An upstream dependency is temporarily unavailable; retry later. |
route_capacity | server_error | 503 | Yes | — | The platform is temporarily at capacity; retry after the interval. |
route_timeout | server_error | 503 | Yes | — | Model selection timed out; retry the request. |
route_unavailable | server_error | 503 | Yes | — | A platform service was restarting or did not respond; retry shortly. |
response_format_schema_too_complex | invalid_request_error | 400 | No | — | The response format schema exceeds the supported complexity. Simplify the schema and retry. |
A 429 can also echo the upstream code insufficient_quota when an upstream quota is exhausted; do not retry until the quota is restored.
Error code reference#
Every non-limit code the platform can emit, with its type, canonical status, and retryability. Stream-frame codes arrive on an in-band error frame after HTTP 200 is committed, so their status column describes the failure class, not a status line.
insufficient_quota#
type rate_limit_error -- status 429 -- retriable: No.
A usage quota backing this request is exhausted; retrying will not clear this standing condition.
unsupported_feature#
type invalid_request_error -- status 400 -- retriable: No.
The request uses an input feature the requested model does not support.
Documented details keys: details.required_features.
capability_conflict#
type invalid_request_error -- status 409 -- retriable: No.
The request combines capabilities that cannot be served together as sent.
Documented details keys: details.lossiness.
context_length_exceeded#
type invalid_request_error -- status 400 -- retriable: No.
The request exceeds the model's context window; reduce the input.
Documented details keys: details.estimated_input_tokens, details.context_window, details.largest_input_item.
upstream_error#
type api_error -- status 502 -- retriable: Yes.
An upstream dependency returned an unexpected error; the error's retryable field says whether a retry can succeed.
upstream_auth_error#
type api_error -- status 502 -- retriable: Yes.
The platform could not authenticate with an upstream dependency; this is a platform-side condition, not an API-key problem. The error's retryable field is false: the platform takes the refused credential out of service itself, and a retry succeeds only once it serves with a working one.
model_not_available#
type forbidden -- status 403 -- retriable: No.
The requested model is not available for this account or API key.
zero_retention_not_supported#
type forbidden -- status 403 -- retriable: No.
The requested model does not support zero data retention yet, so an API key with a zero data retention policy cannot use it.
model_not_found#
type invalid_request_error -- status 404 -- retriable: No.
The requested model is not offered on this endpoint.
previous_response_not_found#
type invalid_request_error -- status 400 -- retriable: No.
previous_response_id names no stored response for this organization: the id is unknown, expired, or was created with store=false.
streaming_not_available#
type forbidden -- status 403 -- retriable: No.
Streaming is not enabled for this API key.
idempotency_key_conflict#
type invalid_request_error -- status 409 -- retriable: No.
The idempotency key was already used by a different request.
bad_request#
type invalid_request_error -- status 400 -- retriable: No.
The request is malformed; the message names what to fix.
invalid_request_error#
type invalid_request_error -- status 400 -- retriable: No.
The request is invalid; correct its content before retrying.
invalid_json#
type invalid_request_error -- status 400 -- retriable: No.
The request body is not valid JSON.
unsupported_media_type#
type invalid_request_error -- status 415 -- retriable: No.
The request body must be uncompressed application/json.
payload_too_large#
type invalid_request_error -- status 413 -- retriable: No.
The request body exceeds the maximum accepted size.
pdf_too_complex#
type invalid_request_error -- status 400 -- retriable: No.
A PDF input needs more processing than the supported bound; reduce its page count or complexity, or split it into smaller files.
request_body_timeout#
type api_error -- status 408 -- retriable: Yes.
The request body stopped arriving before it was complete; send the complete body and retry.
not_found#
type invalid_request_error -- status 404 -- retriable: No.
The requested path or resource does not exist.
method_not_allowed#
type invalid_request_error -- status 405 -- retriable: No.
The endpoint does not accept this HTTP method; the Allow header lists the ones it does.
conflict#
type invalid_request_error -- status 409 -- retriable: No.
The request conflicts with the current state of the resource.
forbidden#
type invalid_request_error -- status 403 -- retriable: No.
The credential is valid but not permitted to perform this operation.
request_requirements_unsatisfied#
type invalid_request_error -- status 400 -- retriable: No.
The request combines inputs or features that cannot be served together.
invalid_metadata#
type invalid_request_error -- status 400 -- retriable: No.
The request metadata must be a JSON object.
invalid_parameter#
type invalid_request_error -- status 400 -- retriable: No.
A request parameter failed validation; the code carries the offending parameter name and error.param names it when known.
The wire code carries the offending parameter name (e.g. invalid_parameter.temperature); error.param names it structurally.
missing_authorization#
type authentication_error -- status 401 -- retriable: No.
No API key was found on the request.
bearer_scheme_required#
type authentication_error -- status 401 -- retriable: No.
An Authorization header was present but did not use the Bearer scheme.
invalid_api_key#
type authentication_error -- status 401 -- retriable: No.
The presented API key was not recognized.
Documented details keys: details.key_hint.
authentication_error#
type authentication_error -- status 401 -- retriable: No.
Legacy 401 code that duplicated the error type verbatim; replaced by the specific authentication codes. Code-matching clients keep working: the old code's value remains as the error type.
Deprecated: replaced by invalid_api_key.
admin_key_required#
type permission_error -- status 403 -- retriable: No.
The endpoint manages an organization and needs an organization admin key.
admin_key_route_forbidden#
type permission_error -- status 403 -- retriable: No.
An organization admin key calls only the organization API, never a model.
api_key_already_registered#
type invalid_request_error -- status 400 -- retriable: No.
The key sent for registration is already registered.
api_key_limit_reached#
type invalid_request_error -- status 409 -- retriable: No.
The organization has as many active API keys as it may hold; revoke one first.
last_admin_key#
type invalid_request_error -- status 409 -- retriable: No.
The key is the organization's last active admin key, so it cannot be revoked.
key_change_limit_reached#
type rate_limit_error -- status 429 -- retriable: Yes.
The organization made as many key changes in the last minute as it may; Retry-After says when the next one is accepted.
api_key_not_yet_active#
type api_error -- status 503 -- retriable: Yes.
The registered key was saved but is not yet active everywhere; sending the same request again is safe.
group_limit_reached#
type invalid_request_error -- status 409 -- retriable: No.
The organization has as many active groups as it may hold; archive one first.
group_external_id_taken#
type invalid_request_error -- status 409 -- retriable: No.
Another group of the organization already carries this external_id.
group_not_empty#
type invalid_request_error -- status 409 -- retriable: No.
The group still holds an active group or an API key that is not revoked, so it cannot be archived.
not_available_for_data_retention#
type invalid_request_error -- status 400 -- retriable: No.
The request asks for something the organization's data retention setting does not allow, such as a tool that runs outside the model that answers it or a longer prompt-cache lifetime; error.param names the field.
internal_error#
type api_error -- status 500 -- retriable: Yes.
An internal error occurred; the request may succeed on retry.
stream_init_error#
type api_error -- status stream frame (class 500) -- retriable: Yes.
The stream failed before the first frame; retry the request.
stream_finalization_error#
type api_error -- status stream frame (class 500) -- retriable: Yes.
The stream failed while finalizing; delivered output was billed as sent.
cancelled#
type api_error -- status stream frame (class 499) -- retriable: No.
The request was cancelled by the client before completion.
provider_error#
type api_error -- status stream frame (class 502) -- retriable: Yes.
An upstream dependency reported an error mid-stream; the frame's type and retryable fields give the class and verdict for that frame.
model_tool_call_invalid#
type api_error -- status 502 -- retriable: Yes.
The model produced a tool call that failed verification, such as an apply_patch edit that is not a valid patch; a retry samples a new call.
Error details#
Limit-class denials attach a machine-readable error.details object next to code and type:
{
"error": {
"message": "Rate limit exceeded. Retry after 1 second.",
"type": "rate_limit_error",
"param": null,
"code": "rate_limit_exceeded",
"details": {
"dimension": "requests",
"scope": "rpm",
"limit": 60,
"window_seconds": 60,
"retry_after_seconds": 0.8
}
}
}
dimension: what ran out, using the vocabulary in the table above.scope: legacy limit marker (rpm,tpm,concurrency,budget,spend). Deprecated: it repeatsdimensionin an older vocabulary, and in a future releasescopewill carry the provenance value now published asbinding_scope. Migrate machine handling todimensionnow.binding_scope: which configuration level produced the limit that denied the request, when known:api_key,org,tier,model, orcapacity.limit: the configured value of the denied limit (account-scoped denials only).estimate: on a token-limit denial, the measured token count it compared againstlimit. Spend denials never carry it.window_seconds: the enforcement window for windowed limits.retry_after_seconds: fractional seconds to wait; theRetry-Afterheader carries the same value rounded up to a whole second.resets_at: on a final daily or monthly spend-cap refusal, when the cap's UTC period ends, as an RFC 3339 timestamp (for example2026-11-07T00:00:00+00:00).
Keys are omitted, never guessed, when a value is unknown. Codes, header names, and details keys are the stable machine contract; message text is not.
Context overflow details#
A context_length_exceeded error reports the size of the request, the limit it was checked against, and the largest item in its input:
{
"error": {
"message": "Request input (~1004493 tokens) exceeds the context window for eb1-frontier-preview. Reduce the input context or summarize prior turns and retry. The largest input item is tool output call_8f2k, about 735K tokens; 42% of its characters are U+FFFD (undecodable bytes), likely a binary file read as text.",
"type": "invalid_request_error",
"param": null,
"code": "context_length_exceeded",
"details": {
"estimated_input_tokens": 1004493,
"context_window": 869811,
"largest_input_item": {
"kind": "tool_output",
"call_id": "call_8f2k",
"estimated_tokens": 734512,
"replacement_char_fraction": 0.42
}
}
}
}
estimated_input_tokens: the request's input size in tokens.context_window: the limit the request was checked against, in the same unit.largest_input_item: the single largest text item in the input: a message, a tool call or tool output, the system prompt, or the tool definitions taken together. Images, files, and replayed reasoning items are not weighed. The object is omitted when no item carries text. -kind:system_prompt,system_message,user_message,assistant_message,tool_call,tool_output,tool_definitions, orinput_item. -call_id: fortool_callandtool_output, the tool call id you sent (tool_call_idon Chat Completions,tool_use_idon Messages) when it uses only letters, digits,_,-,., and:and is at most 128 characters long; otherwisenull. -estimated_tokens: the item's approximate size in tokens. When the overflow is reported by the model rather than detected before the request is sent,estimated_input_tokensandcontext_windoware the model's own counts, which can run higher than this estimate. -replacement_char_fraction: the share of the item's characters that are U+FFFD replacement characters. A binary file such as a PNG decoded as UTF-8 text with replacement measures about0.4; the message notes it from0.25.
On the Messages endpoint the message starts with prompt is too long: {N} tokens > {M} maximum, and the same sentence about the largest item follows it.
Unsupported request fields#
A top-level request field the endpoint does not accept is refused with a 400 invalid_request_error. Its code is the field's name for a documented field Keiro does not implement, such as n or background, and invalid_parameter for any other field. On /v1/messages and /v1/responses, a field Keiro holds back on purpose (Messages service_tier, container or betas; Responses prompt, context_management, access_programs or moderation) is refused with capability_conflict (409) instead, even beside a field refused with a 400. On a model outside the eb1 family, called on its own wire format, a field Keiro does not list is forwarded to that model's API instead, and a rejection there arrives as a 400 invalid_request_error whose message names the fields Keiro forwarded. Only keys with access to models outside the eb1 family can make those requests: any other key gets a 403 model_not_available for a model Keiro offers to other accounts, and a 404 model_not_found for any other model ID.
A refusal's message names your field, and error.param carries it, when the name is an identifier of at most 64 characters (letters, digits and underscores) and at most three fields are refused; otherwise the message is Request contains unsupported fields or features. and param is the first such identifier, if any. details.unsupported_fields always lists every refused field.
{
"error": {
"message": "Request contains an unsupported field: 'example_field'.",
"type": "invalid_request_error",
"param": "example_field",
"code": "invalid_parameter",
"details": {
"is_lossy": true,
"unsupported_fields": ["example_field"],
"unsupported_features": [],
"lossiness": ["unsupported_field_example_field"],
"recommendation": "400"
}
}
}
Structured output conflicts#
A json_schema output format (text.format on /v1/responses, response_format on /v1/chat/completions, output_config.format on /v1/messages) is honored natively and is never degraded to unconstrained prose. When it cannot be honored as sent the request is refused with capability_conflict (409); details.lossiness, when present, names the reason:
structured_output_not_supported: the model serving the request does not support constrained decoding. Remove the output schema or request a model that supports it.json_mode_not_supported: the model serving the request has no JSON mode (json_object), or the format has none (Messages). Send ajson_schemainstead.
strict is forwarded as sent. On served models that gate constrained decoding behind strict: true, a schema sent with strict absent or false is best-effort and is not checked against that model's strict subset; on served models whose grammar enforcement has no strict knob, every schema is enforced. On a best-effort schema turn that also declares tools, the answer is checked once it arrives, streamed or not: a bare JSON object that is a call of one declared tool written as text (an argument object of that tool, with every required parameter present and no key outside its parameters, unless its schema sets additionalProperties, requires parameters, and every required value has the plain type its property declares, or a call record that names the tool beside arguments, input or args) and that the requested schema does not admit is refused as upstream_error (502, or a stream error frame). A schema admits every object whose keys are properties it names at the top level, across anyOf, oneOf and allOf branches and local $ref targets; a schema whose root is an open object, a $ref that cannot be resolved locally, or one that names no properties admits every object. Every other object is forwarded as sent. The /v1/messages spelling carries no strict flag and is lowered with strict: true, so it is enforced on every served model. Some served models enforce strict: true only for schemas in which every object lists all of its properties in required and sets additionalProperties: false. A strict schema outside that subset is refused before dispatch with a 400 invalid_request_error whose param names the schema field (output_config.format.schema on /v1/messages, text.format.schema on /v1/responses, response_format.json_schema.schema on /v1/chat/completions) and whose message states why strictness applies and the two ways out: list every property in required and set additionalProperties: false on every object, or request a model that supports the schema as written. A strict schema is never rewritten and never downgraded to best-effort output; strict schemas inside the subset are accepted by every served model.
Request body limits#
These bounds apply to the request body before it is parsed:
- A body of 28 MiB (29,360,128 bytes) or more is refused with
413payload_too_large. - A body that sends no byte for 60 seconds while it is being read is refused with
408request_body_timeout. The bound is on silence, not on total upload time: an upload that keeps sending is read however long it takes. - A
Content-Encodingother thanidentityis refused with415unsupported_media_type. Send the body uncompressed.
Model refusals#
When the model declines a request and no answer can be delivered, the request ends with code upstream_error, type api_error and retryable: false: status 502 and x-should-retry: false on a non-streaming request, or a stream error frame after 200. The message is The model declined this request. Rephrasing or changing it may help; sending it again unchanged is likely to get the same result. Change the request before you send it again.
This applies to direct model requests. On eb1 requests, Keiro usually handles the refusal itself and returns a completed response. When it can't, you get this error. Direct model requests need a key with access to models outside the eb1 family: any other key gets a 403 model_not_available for a model Keiro offers to other accounts, and a 404 model_not_found for any other model ID.
On a direct model request, if the model stops with a refusal after text has already been delivered, there is no error: the response ends with finish_reason: "content_filter" on Chat Completions, incomplete_details.reason: "content_filter" on Responses, or stop_reason: "refusal" on Messages. Any eb1 request can end that way too. Only a stream can instead end with the error frame above, after text has been delivered, so handle both.
Stream error frames#
Streaming responses commit HTTP status 200 and the response headers before the first body byte, so a failure after that point cannot change the status line. Instead the stream ends with one in-band error frame carrying the same type and code taxonomy as non-streaming error bodies -- including limit denials that strike mid-stream.
Every stream error frame carries these fields:
| Field | Meaning |
|---|---|
type | Failure-class type from the same registry as the code table above. |
code | Machine-readable failure code from the same registry. |
message | Sanitized human-readable description. |
retry_after_seconds | Fractional seconds to wait before retrying; present only when the failure class is retriable. |
Codes that carry retry_after_seconds: capacity_exceeded, connection_limit, gateway_restarting, gateway_timeout, no_capacity, platform_pressure, provider_unavailable, rate_limit_exceeded, route_capacity, route_timeout, route_unavailable, upstream_server_error.
Every wire nests the fields under an error object, which additionally carries retryable (whether an unchanged retry can succeed), request_id (the same correlation id as the X-Request-Id response header), and -- on limit denials and capability conflicts -- the same details object as non-streaming bodies (dimension, binding_scope, limit, and a token estimate on a denial; the capability_conflict keys on a conflict; keys omitted when unknown, never guessed).
Chat Completions additionally delivers the four documented fields flat on the frame payload, exactly as before. The flat keys are deprecated as of 2026-07-15: prefer the nested error object, which OpenAI-compatible SDKs already surface as a typed error. The flat keys will be removed no sooner than two contract releases after this deprecation, and only once usage telemetry shows no remaining flat-key consumers.
A failure the gateway cannot classify ends the stream with type api_error and code internal_error. Its error object carries retryable true and no retry_after_seconds.
Retry safely#
Retry transient 5xx responses -- and 429 responses that do not declare x-should-retry: false -- with exponential backoff and jitter, and honor Retry-After and retry-after-ms whenever they are present; they are computed from actual limiter state. Do not retry malformed requests, invalid credentials, unsupported models, or permission errors without changing the request. Don't retry any error with retryable: false, including a 5xx.
Request identification#
Every response under /v1 carries an X-Request-Id header, and every error body repeats the same value as error.request_id (stream failures carry it inside the error frame's error object on every wire). Responses on /v1/messages and /v1/messages/count_tokens also carry the same value in a lowercase request-id header, the one Messages-format SDKs read. Console surfaces show it as a Reference: line.
When you contact support, paste the request_id (or the whole error body) together with the timestamp, endpoint, and model. The id joins your request to exactly one internal trace; without it, support has to search by time window. Do not send API keys.
The public error contract omits private serving architecture, non-public vendor data, and raw diagnostic payloads.