Errors¶

Error format¶

pokkit errors use a simple JSON envelope:

{
  "error": "Human-readable error message"
}

Errors from upstream providers are passed through as-is (see Pass-through errors below).

pokkit-generated errors¶

401 Unauthorized¶

The bearer token is missing, malformed, or not recognized.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "error": "Unauthorized" }

See Authentication for token requirements.

502 Bad Gateway¶

pokkit was unable to complete the request to the upstream provider. This may be a network failure, an invalid API key configured on the server, or a transient upstream error.

HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{ "error": "Bad gateway" }

If you see this persistently, contact support.

Pass-through errors from upstream¶

If the upstream provider returns a 4xx or 5xx response, it is forwarded to you unchanged — including the status code, body, and headers. This means you may see:

Status	Common cause
`400 Bad Request`	Malformed request body or unsupported parameter for the target provider
`429 Too Many Requests`	Upstream rate limit hit; see Rate limits
`500 Internal Server Error`	Upstream provider fault
`503 Service Unavailable`	Provider overloaded or under maintenance

Distinguishing pokkit errors from upstream errors

pokkit errors have the simple { "error": "..." } format. Upstream provider errors usually have provider-specific JSON bodies (e.g., Anthropic's { "type": "error", "error": { ... } } format).