# Errors

Error types and response fields returned by this API. General API context follows under “More details”.

## Error types

- `invalid_request`
- `invalid_parameter`
- `unsupported_parameter`
- `context_length_exceeded`
- `authentication`
- `insufficient_credits`
- `workspace_budget_exceeded`
- `permission_denied`
- `moderation`
- `model_not_found`
- `no_endpoint`
- `not_found`
- `method_not_allowed`
- `timeout`
- `payload_too_large`
- `media_fetch_failed`
- `rate_limited`
- `provider_error`
- `idempotency_conflict`
- `idempotency_in_progress`
- `idempotency_unavailable`
- `provider_invalid_response`
- `no_provider_available`
- `byok_invalid_credential`
- `byok_rate_limited`
- `byok_unavailable`
- `feature_unavailable`
- `internal`

## Response schema

### s3: object

Every response with an HTTP status of 400 or higher has this shape, OpenRouter's error
format. Everything the gateway adds is inside `error.metadata`, so OpenRouter clients see
nothing unfamiliar. See "Errors" in the introduction for all error types.

{}

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- error (required): s238

### s238: object

What went wrong.

{}

```json
{
  "code": 400,
  "message": "temperature must be at most 2, got 5 (and 1 more)",
  "metadata": {
    "docs_url": "/docs#description/invalid-parameter",
    "issues": [
      {
        "code": "out_of_range",
        "message": "temperature must be at most 2, got 5",
        "path": "$.temperature"
      },
      {
        "code": "invalid_value",
        "message": "messages[1].role must be one of system, developer, user, assistant, tool, got \"bot\"",
        "path": "$.messages[1].role"
      }
    ],
    "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
    "retryable": false,
    "type": "invalid_parameter"
  }
}
```

- code (required): s633

### s633: integer

The HTTP status of the response, as a number.

int32

{"minimum":"0"}

```json
400
```

- message (required): s634

### s634: string

What went wrong, in English. With several problems: the first one and how many more
follow; all of them are in `metadata.issues`. The text may change; match on
`metadata.type` instead.

{}

```json
"temperature must be at most 2, got 5"
```

- metadata (optional): s635

### s635: object

Details for programs: error type, request ID, every problem, a suggested fix and, for
provider errors, which provider failed. Always present on gateway errors.

{}

```json
{
  "docs_url": "/docs#description/rate-limited",
  "provider_error": {
    "category": "rate_limited",
    "provider_name": "deepinfra",
    "retry_after": 2,
    "retryable": true,
    "status": 429
  },
  "provider_name": "deepinfra",
  "remedy_hint": "Retry after the Retry-After interval, or allow fallbacks to other providers (provider.allow_fallbacks).",
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "retry_after": 2,
  "retryable": true,
  "type": "rate_limited"
}
```

- available_providers (optional): s639

### s639: array

Providers that serve the model (when `provider.only` excluded all of them).

{}

```json
[
  "deepinfra",
  "open-inference"
]
```

### s7: string

{}

- docs_url (required): s640

### s640: string

Link to the section of this error type in the documentation.

{}

```json
"/docs#description/model-not-found"
```

- failed_routing_step (optional): s641

### s641: string

The routing step that left no route (routing errors only).

{}

```json
"Filter by Max Price"
```

- issues (optional): s642

### s642: array

Every problem found in the request, so all can be fixed at once (at most 20); for
routing errors one entry per excluded route, for `no_provider_available` one per failed
attempt.

{}

### s123: object

One problem in the request, one reason a route was excluded, or one failed attempt.

{}

```json
{
  "code": "invalid_url",
  "message": "messages[2].content[0].image_url.url must be an http(s) URL or a base64 data URL",
  "path": "$.messages[2].content[0].image_url.url"
}
```

- code (required): s636

### s636: string

Kind of problem, stable for programs.

"required", "invalid_type", "invalid_value", "out_of_range", "empty", "invalid_url", "invalid_base64", "unsupported_media_type", "media_type_mismatch", "media_too_large", "too_many_media", "unsupported_media_transport", "media_fetch_failed", "unknown_tool", "unknown_model", "not_available", "not_allowed", "route_excluded", "bridge_failed", "provider_failed"

{}

```json
"out_of_range"
```

- message (required): s637

### s637: string

The problem in English, naming the field and, if short, the value sent.

{}

```json
"temperature must be at most 2, got 5"
```

- path (required): s638

### s638: string

Where the problem is: JSONPath of the field in the request body, for example
`$.messages[2].content[0].image_url.url`, or `query.<name>` for a query parameter.

{}

```json
"$.temperature"
```

- provider_error (optional): s643

### s643: oneOf

Safe provider diagnostics, identical for HTTP errors and terminal stream events.

{}

oneOf: s1158

### s1158: object

Provider diagnostics without provider-authored text. HTTP and terminal SSE errors use
this same structure; arbitrary upstream messages and metadata are discarded.

{}

```json
{
  "category": "rate_limited",
  "provider_name": "deepinfra",
  "retry_after": 2,
  "retryable": true,
  "status": 429
}
```

- category (required): s1299

### s1299: string

Gateway classification from HTTP status and recognized dialect identifiers.

"rate_limited", "overloaded", "invalid_request", "context_length", "content_filtered", "authentication", "billing", "timeout", "unavailable", "unknown"

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exact identifier from the configured dialect's fixed list; arbitrary values vanish.

{}

```json
"rate_limit_exceeded"
```

- provider_name (required): s1301

### s1301: string

Configured provider name, never a name supplied by the upstream body.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Bounded seconds from the upstream Retry-After header, when present and numeric.

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s1303

### s1303: boolean

Whether the classified failure can be transient. Unknown failures are not promised retryable.

{}

- status (optional): s1304

### s1304: integer

Actual HTTP status received from the upstream, including 200 for native errors.
Absent when no HTTP status is available.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

The provider that failed, as in the response field `provider` (provider errors only).

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserved OpenRouter compatibility field. The gateway never fills it: provider
free text is deliberately withheld. Use provider_error instead.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

A concrete fix, for example the closest model ID to a mistyped one.

{}

```json
"Did you mean deepseek/deepseek-v4.1-flash?"
```

- request_id (required): s647

### s647: string

ID of the request, the same as the `x-request-id` response header. Quote it when
contacting support.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Providers named in `provider.only` (when it excluded all routes).

{}

```json
[
  "scaleway"
]
```

- retry_after (optional): s649

### s649: integer

Seconds to wait before retrying; also sent as the `Retry-After` header (429 and 503).

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s650

### s650: boolean

Whether sending the identical request again can succeed (for example after a timeout
or rate limit), as opposed to errors that need a changed request.

{}

- routing_funnel (optional): s651

### s651: array

How routing narrowed down the providers: each step with the number of routes left
(routing errors only, same format as OpenRouter).

{}

### s200: object

One routing step, as in OpenRouter's `routing_funnel`.

{}

```json
{
  "endpoint_count": 0,
  "reason": "provider.max_price",
  "step": "Filter by Max Price"
}
```

- endpoint_count (required): s979

### s979: integer

Number of routes (providers of the model) left after the step.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

The request field the step filtered on.

{}

```json
"provider.only"
```

- step (required): s981

### s981: string

Name of the step, as at OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (required): s652

### s652: string

Stable error type to match on in code; see "Errors" in the introduction. Messages may
change, the type does not.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal"

{}

```json
"invalid_parameter"
```

- user_id (optional): s239

### s239: string | null

Organization of the API key, if the key was recognized.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## More details

One API for curated language models, served only by European providers. The API is OpenRouter's: existing OpenRouter or OpenAI clients work after changing the base URL to this server's `/v1` and the API key (`Authorization: Bearer <key>`). Model IDs are the same as on OpenRouter, for example `deepseek/deepseek-v4.1-flash`.

Browser clients may call this bearer-token API from any origin. CORS preflights need no API key; cookies are not used. Responses carry CORS headers when the request includes `Origin`. The specification is served at `/openapi.json`; `/docs` redirects to the configured dashboard documentation, or returns 404 when no documentation URL is configured.

## Differences from OpenRouter

- **Euros:** every price and cost is in EUR. Prices in `GET /v1/models` are EUR per token with `currency: "EUR"`, `usage.cost` is EUR, and `provider.max_price` in requests is EUR per million tokens. Providers that price in another currency are converted with the gateway's exchange rate valid when the request arrives (input and output cost each rounded down to whole picos); `usage.cost_details.original` and `pricing.original` in `GET /v1/models` show their own prices and the rate.
- **Checked before any provider is called:** invalid requests fail at once with 400 and a list of every problem (`error.metadata.issues`), instead of failing at the provider.
- **Unknown parameters** are ignored, as on OpenRouter, and named in the `x-ignored-params` response header.
- **Error details:** errors keep OpenRouter's shape; `error.metadata` adds a stable `type`, the `request_id` (also in the `x-request-id` header of every response), a suggested fix and whether a retry helps (see Errors).
- **API keys:** `GET /v1/key` has OpenRouter's format, with amounts in EUR also in fields named `*_usd`. A key can be limited to certain models (403 `permission_denied`, the hint names the allowed ones) and can expire (401 `authentication`).
- **Endpoint coverage:** `GET /v1/credits`, `GET /v1/providers`, `GET /v1/models/{author}/{slug}/endpoints` and legacy `POST /v1/completions` are not offered. Use `GET /v1/key` for gateway credits, `GET /v1/models` (including each model's `routes`) for providers and endpoints, and `POST /v1/chat/completions` for generation. `/api/v1` is not an alias; replace the full base URL with `/v1`.
- **Providers:** only European providers serve requests; if one fails before sending output, the gateway tries the next one. With `provider.sort` set to `latency` or `throughput`, the gateway ranks providers by its own measurements of the last 30 minutes.
- **Aliases:** besides OpenRouter's model IDs, `model` accepts aliases such as `eu/fast` (current recommended version) and `eu/fast@2026-10` (pinned). Responses name the model behind the alias; `GET /v1/models` lists aliases with that model in `canonical_slug`.
- **Generations:** `GET /v1/generation?id=` has OpenRouter's format with costs in EUR. A gateway instance keeps its most recent generations in memory; only keys of the same organization see them. `GET /v1/generation/content?id=` returns prompt and answer only for API keys whose policy allows content capture; without it, nothing of the content is stored. Requests with the same `x-session-id` header or `session_id` field form a session: `GET /v1/sessions/{id}` lists its generations. A request whose messages continue an earlier request of the same key gets that generation as `parent_id` (agent chains without an SDK); `GET /v1/generation/chain?id=` lists the chain.
- **Time breakdown:** every generation also shows where its time went: `gateway_overhead` (the gateway's own work), `queue_time` (waiting for memory budgets) and `timings` per phase, in milliseconds. Inference responses carry the same phases in a `Server-Timing` header, with `upstream` for all provider attempts as a whole and no provider names.

## Limits

The time limits are defaults; a model's provider can have longer ones, for example for reasoning models that think before their first token.

| Limit | Value | When exceeded |
|---|---|---|
| Request deadline across preprocessing, retries and fallback | 600 s | 408 `timeout`; a committed stream retains its idle timeout, with no retry after commitment |
| Request body | 50 MiB | 413 `payload_too_large`; send images and files as URLs |
| Parsed request structure excluding JSON string values (estimated before parsing) | 20 MiB | 413 `payload_too_large` (only bodies of hundreds of thousands of small values reach it) |
| Zstd request window / concatenated frames | 8 MiB / 64 | 413 `payload_too_large`; both encoded and decoded bodies retain the request limit; invalid framing/checksum returns 400 `invalid_request` |
| Pause while the request body is uploaded | 30 s | 408 `timeout` |
| Wait for memory while the gateway is busy with other large bodies | 5 s | 503 `no_provider_available` with `Retry-After` |
| Requests waiting for memory at the same time | 512 | 503 `no_provider_available` with `Retry-After` at once |
| Wait for memory while the gateway is busy with other large non-streaming responses | 5 s | 503 `no_provider_available` with `Retry-After`; the provider's response is dropped |
| Problems listed in `issues` | 20 | the message says how many more there are |
| Inputs in one embeddings request | 2048 | 400 `invalid_parameter`; split the inputs into several requests |
| Audio to transcribe | the request body | 413 `payload_too_large`; as base64 JSON the 50 MiB body holds about 37 MiB of audio, an upload nearly 50 MiB |
| Context estimate (prompt length) | 4 bytes per token | 400 `context_length_exceeded` above the model's `context_length` (embeddings: per input) |
| Connecting to a provider | 10 s | 408 `timeout`; the next provider is tried |
| Streams: time to the first nonempty data event (comments do not count) | 120 s | 408 `timeout`; the next provider is tried |
| Streams: silence between two chunks (no limit on total duration) | 120 s | final error event `timeout`, then `[DONE]` |
| Streams: quiet time before a `: keepalive` comment | 15 s | not an error; SSE parsers skip comments |
| Non-streaming: time to the first response body byte | 120 s | 408 `timeout`; at most one further attempt within retry settings and the shared deadline |
| Non-streaming: complete response | 600 s | 408 `timeout`; the next provider is tried (stream long answers) |
| Non-streaming provider response | 32 MiB | 502 `provider_invalid_response`; the next provider is tried |
| Memory of the parsed provider response beyond its size | 20 MiB | 502 `provider_invalid_response`; the next provider is tried |
| One stream event from a provider | 1 MiB | final error event `provider_invalid_response` |
| Captured content per generation (`GET /v1/generation/content`) | 768 KiB of messages, 256 KiB of answer | the rest is cut and marked with `truncated` |
| Captured content kept per gateway instance | 32 MiB | the oldest content is dropped first; its metadata stays |
| Generations listed by `GET /v1/sessions/{id}` and `GET /v1/generation/chain` | 500 | the most recent ones; `total` or `truncated` says that more exist |
| Earlier conversations checked as parent of a request (agent chains) | 16 | the longest ones; a continuation of a shorter one starts a new chain |
| Running requests when an instance shuts down | 25 s | 503 `no_provider_available` (streams: final error event) |

### Retry and fallback

Transient provider errors before the response is committed may be retried on the same route before fallback: HTTP 408/429/500/502/503/504/529, connection failures and timeouts, provided the error dialect also classifies them as transient. Native errors inside successful HTTP responses are also retried when the configured dialect classifies them as transient. Other 4xx, malformed responses and local quota rejections are not retried.

The gateway configuration accepts `retry: {max_attempts, base_ms, max_ms}` globally and as a complete per-route override. Defaults are one total attempt (retries are opt-in to preserve existing quota reservations), 1000 ms initial backoff ceiling and 10000 ms maximum wait. Attempts must be 1..=8; `max_attempts: 1` disables retries. Equal jitter selects the upper half of each capped exponential interval. Numeric `Retry-After` is a minimum; a delay above `max_ms` or the remaining deadline skips to fallback. `request_deadline_ms` defaults to 600000 and is shared by all attempts, never reset per route. Stream startup uses `timeouts.first_byte_ms` until the first nonempty SSE data event; comments and empty data events never extend this fixed deadline. Non-streaming startup uses the independent `timeouts.nonstream_first_byte_ms` until the first body byte; response headers alone do not count. Both default to 120000 ms and allow per-route overrides. Non-streaming `response_ms` still bounds the entire response. After a startup timeout, at most one further actual attempt is allowed across same-route retries and fallback, without increasing configured retry or spending limits. All actual attempts count toward provider health and account limits and appear in generation history. Costs and customer tokens are reserved conservatively for every possible attempt. The existing overall limit of 16 recorded attempts still applies. Cancellation drops the wait and upstream future. This is gateway behavior, not a claim about OpenRouter's retry policy.


## Errors

Every error has OpenRouter's shape `{"error": {"code", "message", "metadata"}, "user_id"}`. `metadata.type` is the stable error type below; `metadata.request_id` equals the `x-request-id` header. Validation errors list every problem in `metadata.issues` (JSONPath, code, message). `metadata.remedy_hint` suggests a fix, `metadata.retryable` says whether retrying helps, and 429 and 503 carry `Retry-After`. Provider errors add `provider_name` and structured `provider_error` diagnostics; provider text is withheld. Unlike OpenRouter, `raw` is never filled, including for captured generations. Errors after the first byte of a stream arrive as a final event with the same `error` object and a choice with `finish_reason: "error"`, followed by `[DONE]`. Unknown parameters are not an error: they are ignored and named in the `x-ignored-params` header.

| Type | Status | Retryable |
|---|---|---|
| [`invalid_request`](#description/invalid-request) | 400 | no |
| [`invalid_parameter`](#description/invalid-parameter) | 400 | no |
| [`unsupported_parameter`](#description/unsupported-parameter) | 400 | no |
| [`context_length_exceeded`](#description/context-length-exceeded) | 400 | no |
| [`authentication`](#description/authentication) | 401 | no |
| [`insufficient_credits`](#description/insufficient-credits) | 402 | no |
| [`workspace_budget_exceeded`](#description/workspace-budget-exceeded) | 402 | no |
| [`permission_denied`](#description/permission-denied) | 403 | no |
| [`moderation`](#description/moderation) | 403 | no |
| [`model_not_found`](#description/model-not-found) | 400 | no |
| [`no_endpoint`](#description/no-endpoint) | 404 | no |
| [`not_found`](#description/not-found) | 404 | no |
| [`method_not_allowed`](#description/method-not-allowed) | 405 | no |
| [`timeout`](#description/timeout) | 408 | yes |
| [`payload_too_large`](#description/payload-too-large) | 413 | no |
| [`media_fetch_failed`](#description/media-fetch-failed) | 400 | no |
| [`rate_limited`](#description/rate-limited) | 429 | yes |
| [`provider_error`](#description/provider-error) | 502 | yes |
| [`idempotency_conflict`](#description/idempotency-conflict) | 409 | no |
| [`idempotency_in_progress`](#description/idempotency-in-progress) | 409 | yes |
| [`idempotency_unavailable`](#description/idempotency-unavailable) | 409 | no |
| [`provider_invalid_response`](#description/provider-invalid-response) | 502 | yes |
| [`no_provider_available`](#description/no-provider-available) | 503 | yes |
| [`byok_invalid_credential`](#description/byok-invalid-credential) | 502 | no |
| [`byok_rate_limited`](#description/byok-rate-limited) | 429 | yes |
| [`byok_unavailable`](#description/byok-unavailable) | 503 | yes |
| [`feature_unavailable`](#description/feature-unavailable) | 501 | no |
| [`internal`](#description/internal) | 500 | yes |

### invalid_request

HTTP 400, default message: *The request body is not a valid JSON object*

The body could not be read as a JSON object (broken JSON, empty body, not an object). The `Content-Type` header is not checked, like at OpenRouter.

### invalid_parameter

HTTP 400, default message: *The request contains invalid parameters*

Fields are missing or have invalid values. `issues` lists every problem with its JSONPath, so all of them can be fixed at once. Unlike OpenRouter, which passes many such requests on and lets the provider reject them (often as 422 or a provider error), the gateway checks them before any provider is called: roles, content parts, media URLs and base64 data, `response_format`, tool schemas, `tool_choice`, number ranges such as `temperature` (0 to 2).

### unsupported_parameter

HTTP 400, default message: *The request contains an unsupported parameter*

Reserved; not returned at the moment. Unknown parameters are no error: they are ignored, as on OpenRouter, and named in the `x-ignored-params` response header. Parameters the chosen provider does not support are dropped, or rule the provider out with `provider.require_parameters: true` (then `no_endpoint`).

### context_length_exceeded

HTTP 400, default message: *The request exceeds the model's context length*

The estimated prompt length plus `max_tokens` exceeds the context length (`context_length` in `GET /v1/models`) of every route of the model. The estimate counts 4 bytes of text per token, before any provider is called. Shorten the messages, lower `max_tokens` or choose a model with a longer context.

### authentication

HTTP 401, default message: *Missing Authentication header*

Send the API key as `Authorization: Bearer <key>`. Unknown and expired keys get this error too; for an expired key the message names the expiry time. Expiry is checked when a request starts, so a running stream finishes.

### insufficient_credits

HTTP 402, default message: *Insufficient credits*

Two causes share this type; `message` and `remedy_hint` name the one that applies. (1) The key's EUR spending limit cannot cover this request's reservation plus concurrent reservations: ask the key owner to raise the limit, wait for running requests or the UTC reset. (2) The organization's prepaid EUR credits cannot cover the reservation: top up the organization's credits in the dashboard or wait for running requests to release reservations. Text requests reserve the estimated prompt plus the output allowance: lower max_tokens or max_completion_tokens if honored by the route, or shorten the input. Without an effective output limit, the route's default output allowance is reserved (16384 tokens unless configured otherwise). Media input (image, audio, video or native file) reserves the whole route context as prompt regardless of file size or output limits: send text instead or choose a smaller-context or cheaper route. Before OCR, each file-parser PDF reserves the configured maximum document cost (up to 1000 pages): send fewer PDFs or extracted text; fewer pages in the same PDF and lower output limits do not reduce that reserve. Transcription reserves the route's maximum audio duration regardless of actual duration or file size: choose a route with a shorter duration bound or lower audio prices. Usage beyond the reservation is booked afterwards. The workspace budget has its own type, `workspace_budget_exceeded`.

### workspace_budget_exceeded

HTTP 402, default message: *The workspace budget cannot cover the request*

The budget of the key's workspace, shared by all its keys, cannot cover this request's reservation plus concurrent reservations. Wait for running requests or the UTC reset, or ask a workspace administrator to raise the workspace budget. A request must also pass the key's limit and the organization's credits. The remedy follows the reservation cause as for `insufficient_credits`: lower effective output limits for text, replace media with text or choose a smaller-context route, send fewer OCR PDFs or extracted text, or choose a transcription route with a shorter maximum duration or lower audio prices. Smaller media files, fewer pages within the same OCR PDF and lower output limits do not reduce those input reserves. Usage beyond the reservation is booked afterwards.

### permission_denied

HTTP 403, default message: *This API key is not allowed to make this request*

The policy of the organization, the workspace or the key forbids this request: the model in `model` is not among the allowed models, or the level named in `issues` denies it. `issues` names every requested model that may not be used and the level that refuses it, `remedy_hint` the models that may be used. Fallbacks in `models` that may not be used are skipped without an error.

### moderation

HTTP 403, default message: *The input was flagged by moderation*

Reserved; not returned at the moment, the gateway does not moderate input. Change the input; repeating it unchanged fails again.

### model_not_found

HTTP 400, default message: *The model is not a valid model ID*

The model ID is not in the catalog. `remedy_hint` suggests the closest ID, `GET /v1/models` lists all of them.

### no_endpoint

HTTP 404, default message: *No endpoints found that can serve this request*

The model exists, but none of its providers (routes) fits the request: `provider` filters (`only`, `ignore`), `provider.max_price` (EUR per million tokens), media the model does not accept, or parameters a provider lacks with `provider.require_parameters: true`. `issues` names the reason per provider, `failed_routing_step` the step that left none.

### not_found

HTTP 404, default message: *Not found*

The path does not exist, or the resource it names does not: `GET /v1/generation` answers this for unknown IDs and for generations of other organizations alike. Check the URL; the API is served under `/v1`.

### method_not_allowed

HTTP 405, default message: *The path does not accept this HTTP method*

The path exists but does not accept the HTTP method. The `Allow` header and `remedy_hint` name the methods it accepts.

### timeout

HTTP 408, default message: *The provider did not respond in time*

The provider did not answer within one of the time limits (see Limits), or the request body stopped arriving. Streams are limited in the time to their first byte and in the silence between two chunks, not in total; non-streaming responses have an upper limit. Before the first byte the gateway tries the next provider; after the first byte of a stream, a timeout arrives as the final error event. Retrying usually helps; for long answers, stream.

### payload_too_large

HTTP 413, default message: *The request body is too large*

The body is larger than 50 MiB, or its parsed JSON structure excluding JSON string values would need more than 20 MiB (hundreds of thousands of small values). Send images and files as URLs instead of inline base64 data, and fewer, larger parts instead of many small JSON objects.

### media_fetch_failed

HTTP 400, default message: *The media URL could not be loaded safely*

A route needs inline media, but its URL is blocked, unavailable, too slow, too large, or has an unaccepted type/signature. The issues name input fields and safe reasons without exposing addresses or URL values. Use a reachable public HTTP(S) source, send accepted inline data, or select another eligible route.

### rate_limited

HTTP 429, default message: *The provider is rate limited*

Wait `retry_after` seconds (also in the `Retry-After` header) before retrying, or allow fallbacks to other providers.

### provider_error

HTTP 502, default message: *Provider returned error*

The provider rejected or failed the request. `provider_error.category`, the upstream HTTP status and any recognized code help distinguish transient failures from rejected requests. Provider free text is withheld.

### idempotency_conflict

HTTP 409, default message: *This idempotency key was already used for a different request*

Use a new Idempotency-Key for changed method, path or request content. A key is scoped to one API key identity.

### idempotency_in_progress

HTTP 409, default message: *The original request is still in progress*

Wait for Retry-After and retry the identical request with the same Idempotency-Key. No second provider request is started.

### idempotency_unavailable

HTTP 409, default message: *The original response cannot be replayed safely*

The answer exceeded the configured cache size or safe shared replay state was lost. Use a new Idempotency-Key only when deliberately starting a new, billable request.

### provider_invalid_response

HTTP 502, default message: *The provider returned an invalid response*

The provider sent a response the gateway could not interpret: broken JSON or stream, fields of the wrong type, a response above 32 MiB, or one whose JSON would need more than 20 MiB of memory beyond its size (see Limits). Before the first byte the gateway tries the next provider. Retrying usually helps.

### no_provider_available

HTTP 503, default message: *No provider was able to serve the request*

Every route and fallback failed before producing output (`issues` lists each attempt), no current exchange rate is available to price the model's providers in EUR (`issues` names each route), the gateway is busy with other large request bodies (it waits up to 5 seconds for memory first), or this gateway instance is shutting down (running streams then end with this error event). Retry after `retry_after` seconds.

### byok_invalid_credential

HTTP 502, default message: *The customer provider credential was rejected*

Ask an organization administrator to replace or adjust the provider credential. A 401 blocks this exact credential revision; 403 denotes missing provider permissions. Other organizations and platform provider health are unaffected.

### byok_rate_limited

HTTP 429, default message: *The customer provider credential is rate limited*

Wait for the bounded Retry-After interval. The cooldown affects only the selected organization's credential revision, never another customer or the platform account.

### byok_unavailable

HTTP 503, default message: *No authorized customer provider credential is available*

Ask an organization administrator to check credential status, workspace/key grants, funding mode and current policies. Missing or stale credential synchronization fails closed; platform fallback requires explicit permission.

### feature_unavailable

HTTP 501, default message: *The required feature is not configured on this gateway*

A required feature is permanently unconfigured on this gateway, for example encrypted idempotency replay without its encryption key, PII redaction without a detector, or BYOK import without import keys. Ask the operator to configure it or remove the optional feature from the request. Retrying the identical request cannot enable the feature: retryable is false and no Retry-After header is sent. Temporary cache, database, detector or provider outages, pending imports and missing or revoked individual customer credentials retain their existing error types.

### internal

HTTP 500, default message: *Internal server error*

An unexpected error in the gateway. Retry; if it persists, contact support with the `request_id`.

