API Errors

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

{
  "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.
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.

Gateway API

AI Gateway

Models

Toolken API

Error body shape

Error codes

Provider errors

​Error body shape

​Error codes

​Provider errors

Error body shape

Error codes

Provider errors