> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Errors

> Gateway error response shape and every error code the gateway can return, grounded in the source.

When the gateway itself cannot forward your request, it returns a JSON error body. Provider errors are sanitized and forwarded in the same shape.

## Error body shape

```json theme={null}
{
  "error": {
    "message": "Human-readable description of the error.",
    "type": "proxy_error",
    "param": null,
    "code": "error_code_slug"
  }
}
```

| Field     | Type   | Description                                                                                 |
| --------- | ------ | ------------------------------------------------------------------------------------------- |
| `message` | string | Human-readable description.                                                                 |
| `type`    | string | `proxy_error` for gateway-generated errors. `provider_error` for sanitized upstream errors. |
| `param`   | null   | Always null for gateway errors.                                                             |
| `code`    | string | Machine-readable slug. See the table below.                                                 |

## Error codes

| HTTP status | Code                      | Meaning                                                                                                                                                    | What to do                                                                                                                   |
| ----------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 400         | `invalid_provider`        | The `X-Toolken-Provider` header value is not a recognized provider name.                                                                                   | Check the header value against the [supported providers list](/api-reference/overview#provider-detection).                   |
| 400         | `incompatible_path`       | The detected provider does not support the requested path (e.g. a Claude model sent to `/v1/chat/completions`, or an OpenAI model sent to `/v1/messages`). | Use the correct path for the provider: `/v1/chat/completions` for OpenAI-compatible providers, `/v1/messages` for Anthropic. |
| 401         | `missing_api_key`         | The `X-Toolken-Key` header was not included in the request.                                                                                                | Add `X-Toolken-Key: <your-key>` to every request.                                                                            |
| 401         | `invalid_api_key`         | The `X-Toolken-Key` value does not match any active API key in your workspace.                                                                             | Verify the key is correct and has not been revoked in the Toolken dashboard.                                                 |
| 403         | `tenant_suspended`        | Your workspace has been suspended.                                                                                                                         | Contact Toolken support.                                                                                                     |
| 413         | `payload_too_large`       | The request body exceeds the allowed size limit.                                                                                                           | Reduce the request body size.                                                                                                |
| 422         | `invalid_metadata`        | The metadata in `X-Toolken-Metadata` is valid JSON but contains an invalid key, or exceeds the size or key-count limit.                                    | Use lowercase snake\_case keys starting with a letter (up to 64 characters). Keep the object under 16 KB and 64 keys.        |
| 429         | `rate_limited`            | The request rate limit for your workspace has been exceeded.                                                                                               | Implement exponential backoff and retry.                                                                                     |
| 429         | `concurrent_stream_limit` | Too many simultaneous streaming requests are open for your workspace.                                                                                      | Close idle streams and retry.                                                                                                |
| 502         | `provider_unreachable`    | The gateway could not establish a connection to the upstream provider.                                                                                     | Retry with backoff. Check the provider status page.                                                                          |
| 502         | `response_too_large`      | The provider response exceeded the gateway size limit.                                                                                                     | Use streaming (`stream: true`) for large responses, or reduce `max_tokens`.                                                  |
| 503         | `auth_unavailable`        | The authentication service is temporarily unavailable. The gateway fails closed -- requests are never passed through unauthenticated.                      | Retry with backoff.                                                                                                          |
| 503         | `tenant_unavailable`      | Workspace data could not be loaded. The gateway fails closed.                                                                                              | Retry with backoff.                                                                                                          |
| 504         | `gateway_timeout`         | The upstream provider did not respond within the timeout window.                                                                                           | Retry with backoff. For large requests, consider streaming.                                                                  |

## Provider errors

When the provider itself returns an error (e.g. 400 from OpenAI for an invalid model), the gateway sanitizes the response body -- stripping any credential echoes -- and forwards it in the same `{ error: { message, type, param, code } }` shape with `type: "provider_error"`. The HTTP status code from the provider is preserved.