Skip to content

Router.Africa — API Error Catalogue

Every error api.router.africa returns: the body shape, status codes, headers, and what a client should do. Written for task P1.08. It implements the decisions log entry API error contract and response extras; where they disagree, the decisions log wins.

This is a contract. apps/api must emit exactly these errors, the curated OpenAPI spec (Track D, D.06) describes them, and the developer docs publish them. Adding a reason is a decision; renaming or removing one is a breaking change.

OpenRouter’s envelope, so client code ported from OpenRouter keeps working, with only the error types we actually emit:

{
"error": {
"code": 402,
"message": "This workspace doesn't have enough credits for this request. Add credits at https://app.router.africa.",
"metadata": {
"error_type": "payment_required",
"reason": "insufficient_credits"
}
}
}
Field Meaning
error.code The HTTP status, as a number (OpenRouter’s convention)
error.message Human-readable, safe to show. Never contains a full key, a provider name, gateway details, or prompt content
error.metadata.error_type The portable category, from OpenRouter’s error_type vocabulary (section 3). Branch on this for retry logic
error.metadata.reason Our specific cause, e.g. insufficient_credits versus key_spend_cap_exceeded, which share payment_required. Branch on this for user-facing handling
error.metadata.* Optional extra fields listed per reason below (e.g. model on model_not_found). Nothing else

OpenAI SDK compatibility. OpenAI’s SDKs pick the exception class from the HTTP status and read error.message, so they work unchanged; error.code is a number rather than OpenAI’s string, as with OpenRouter. This replaces the OpenAI-style type and string code proposed in auth-security.md 2.3.

Never in an error: the provider or gateway’s own message or status (mapped, section 5), a stack trace, any header value, any part of the prompt or response.

Header When
x-request-id On every response, success or error. Our request id: the same one in the request log and sent to the gateway, so support requests line up
WWW-Authenticate: Bearer realm="router.africa" On every 401
Retry-After (seconds) Always on 429, 503 and 529. The value is the gateway’s when it gives one, else the edge block time for edge_rate_limited, else the default of 5 seconds (a small constant: the API doesn’t know the org’s rate-limit window at that point, and 5 s is long enough not to invite a retry loop yet short enough not to stall a client on a one-off limit)
x-idempotent-replay: true A Router.Africa extension, not part of OpenAI’s or OpenRouter’s API. Sent only when the response is a stored replay of an earlier identical request (same body, or same Idempotency-Key, see the decisions log, Idempotency key design) rather than a new run. A replay isn’t charged again. Absent on a new run
x-ratelimit-* Not sent. Rate limits are set per org and are not shown to customers (decisions log, Rate limiting / abuse prevention). Clients back off on 429 using Retry-After

error_type values come from OpenRouter’s taxonomy (openrouter-api-comparison.md 1.4); we emit only the ones in this table.

Status error_type reason When Message (template) Client should
400 invalid_request invalid_body Body isn’t valid JSON or fails validation Request body is invalid: <detail>. Fix the request
400 invalid_request key_not_in_header A key was sent in the query string or body (auth-security.md 2.1) Send your API key in the Authorization header, not the URL or body. Move the key to the header; consider rotating it
400 context_length_exceeded context_length_exceeded The provider rejects the prompt as too long The request is too long for <model>’s context window. Shorten the input and retry. Shorten the input
401 authentication missing_api_key No Authorization header, or not Bearer (on POST /v1/messages, also no x-api-key) You didn’t provide an API key. Send it as Authorization: Bearer YOUR_KEY. Add the header
401 authentication invalid_api_key Key unknown, malformed, revoked, expired or still pending; one answer for all of them Incorrect API key provided: sk-ra-…abcd. Check your keys at https://app.router.africa. Use a valid key. Don’t retry
402 payment_required insufficient_credits Available credits (balance minus held) are below the minimum hold, or below what the request needs This workspace doesn’t have enough credits for this request. Add credits at https://app.router.africa. Top up. Don’t retry until then
402 payment_required key_spend_cap_exceeded The key’s spend cap is reached: the user cap (Postgres) or the admin cap (gateway budget). One answer for both This API key has reached its spend limit. Raise the limit or use another key. Raise the cap, wait for the cap period to reset, or switch keys
403 permission_denied account_suspended The org is suspended, or the workspace is frozen or deleted (decisions log, Org suspension) This account is suspended. Contact support. Contact support. Don’t retry
403 content_policy_violation content_policy_violation The provider refuses the content The request was blocked by the model provider’s content policy. Change the content
404 not_found model_not_found Model unknown, off, or not allowed for this key; one answer for all three The model <model> does not exist or you do not have access to it. Check the model id and the key’s allowed models. metadata.model = what was sent
404 not_found route_not_found Unknown path or method No such endpoint. Check the URL and method. Check the endpoint
409 invalid_request request_in_progress An identical request (same body, or same Idempotency-Key) is still running An identical request is already in progress. Wait and retry; the first request’s result will be returned
413 payload_too_large payload_too_large Body over the 16 MiB limit, checked before buffering (auth-security.md 2.1) The request body is too large. Send less than 16 MiB. Send less
429 rate_limit_exceeded rate_limited The key’s rate limit (gateway) is hit Rate limit reached for this API key. Retry after <n> seconds. (<n> is the Retry-After value, always present) Back off; honour Retry-After
429 rate_limit_exceeded concurrency_limited The org already has organizations.max_in_flight requests running (default 20, across all its workspaces and keys). Checked inside core.claim_and_hold; the claim is rolled back, nothing is held or charged Too many requests are running at once for this account. Wait for some to finish, then retry. Wait for running requests to finish, then retry; honour Retry-After
429 rate_limit_exceeded edge_rate_limited The per-IP edge rule at Cloudflare is hit (decisions log, Edge rate limiting), or the client IP has more than 30 rejected key lookups a minute (AUTH_FAILURE_LIMITER, auth-security.md 2.1) Too many requests from this address. Retry after <n> seconds. Back off; honour Retry-After
408 timeout upstream_timeout The gateway gave up after its own retries and fallbacks The model provider took too long to respond. Retry with backoff
500 server internal_error A bug or misconfiguration on our side (including the gateway rejecting our own credentials) Something went wrong on our side. Reference: <request id>. Retry once; contact support with the request id
502 provider_unavailable provider_error The provider returned an error after the gateway’s fallbacks The model provider returned an error. Retry with backoff
503 server service_unavailable We can’t place the hold (database unreachable); the request is refused before any model is called The service is temporarily unavailable. Retry with backoff
529 provider_overloaded provider_overloaded The provider is overloaded and fallbacks are exhausted The model provider is overloaded. Retry shortly. Retry with backoff

Why 402 for money, not 429. auth-security.md 2.4 left this open: OpenAI uses 429 for exhausted balance, but OpenAI’s SDKs retry 429s automatically, so “no credits” would be retried pointlessly. OpenRouter uses 402 for insufficient credits, and SDKs don’t retry it. Since we adopted OpenRouter’s envelope, money errors are 402. Flagged for review (decision made while writing the catalogue).

max_tokens is capped, not an error (decided 2026-11-07). A max_tokens (or max_output_tokens) above the model’s ceiling is silently lowered to the ceiling, so there is no max_tokens_above_limit reason. The earlier row and the max_tokens_exceeded type are removed.

Same answer on purpose. invalid_api_key, model_not_found and key_spend_cap_exceeded each cover several causes, so nobody can probe whether a key existed, which models exist, or which cap applies (auth-security.md 2.3).

Edge 429s come from Cloudflare. The rate-limiting rule must be configured with a custom JSON response matching this envelope, including reason: edge_rate_limited (task P8.07 / P9.05), with a Retry-After header and the message Retry after <n> seconds. filled in. x-request-id isn’t available there.

  • An error before the first token is a normal HTTP error response from this catalogue.
  • An error after streaming has started can’t change the 200 status. It is sent as a final SSE event, data: {"error": {…same envelope…}}, then the stream ends. Settlement uses the gateway’s reported partial usage (decisions log, Mid-stream client disconnect policy).

5. Gateway and provider errors (mapping in the adapter)

Section titled “5. Gateway and provider errors (mapping in the adapter)”

The gateway adapter maps every gateway response to this catalogue; nothing gateway-specific passes through.

Gateway says We return
Virtual key rejected (401/403 from the gateway) 500 internal_error. It’s our credential, not the customer’s; alerts fire
Budget exceeded (gateway 402, the admin USD cap) 402 key_spend_cap_exceeded
Rate limit (gateway 429) 429 rate_limited, with Retry-After: the gateway’s value, else the 5 s default
Model not allowed for the virtual key 404 model_not_found (also signals config drift; key reconciliation should catch it)
Provider 400 context-length error 400 context_length_exceeded
Provider content refusal 403 content_policy_violation
Timeout after fallbacks 408 upstream_timeout
Provider overloaded after fallbacks 529 provider_overloaded
Any other provider error after fallbacks 502 provider_error
Anything unrecognised 500 internal_error, logged with the raw gateway response (never returned)

Every gateway rejection releases the hold (decisions log, Credit hold/settle mechanism).

7. POST /v1/messages: Anthropic’s error format (decided 2026-11-07)

Section titled “7. POST /v1/messages: Anthropic’s error format (decided 2026-11-07)”

Anthropic SDKs parse Anthropic’s error body, so only on POST /v1/messages (and any error that route returns, including auth and route_not_found) the body is:

{
"type": "error",
"error": {
"type": "authentication_error",
"message": "You didn't provide an API key. Send it as `x-api-key: YOUR_KEY` or `Authorization: Bearer YOUR_KEY`.",
"reason": "missing_api_key"
}
}

error.type is Anthropic’s type, chosen from the HTTP status (below). error.reason is our specific cause, the same values as metadata.reason in section 3; per-reason extras (e.g. model on model_not_found) sit beside it inside error. message is the same text as section 3. Status codes and headers (x-request-id, WWW-Authenticate, Retry-After, x-idempotent-replay) are unchanged. There is no error.code and no metadata here.

Status Anthropic error.type Notes
400, 409, 413 invalid_request_error Includes invalid_body, key_not_in_header, context_length_exceeded, request_in_progress, payload_too_large
401 authentication_error missing_api_key, invalid_api_key
402 billing_error insufficient_credits, key_spend_cap_exceeded
403 permission_error account_suspended, content_policy_violation
404 not_found_error model_not_found, route_not_found
429 rate_limit_error rate_limited, concurrency_limited, edge_rate_limited; Retry-After always sent
408, 500, 502, 503 api_error upstream_timeout, internal_error, provider_error, service_unavailable
529 overloaded_error provider_overloaded; Retry-After always sent

Mid-stream errors. After streaming has started the status is already 200, so the error is a final SSE event in Anthropic’s format, then the stream ends:

event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"The model provider is overloaded. Retry shortly.","reason":"provider_overloaded"}}

Implementation: errorResponse in apps/api switches to this body for the /v1/messages path; the route (P0.13) must emit the event: error event for mid-stream failures. The edge 429s from Cloudflare (section 3) are not on a path the edge can tell apart and keep the standard envelope.

  • auth-security.md 2.3 and 2.4: the OpenAI-style type / string code and the open 402-versus-429 question are replaced by this catalogue.
  • api-surface.md section 6: the error-format item is complete.
  • POST /v1/messages follows section 7 (Anthropic’s format) instead of section 1; POST /v1/responses uses the section 1 envelope.
  • Track D: D.06 encodes this in the OpenAPI spec, with an example per row; D.08 writes the Errors page from it.
  • Phase 3: P3.01 (adapter mapping), P3.02 (auth errors) and P3.10 (conformance tests) implement it; the conformance suite should assert every row it can trigger.