Operations
Errors
Mintoken uses standard HTTP status codes. Mintoken-specific errors are returned with a JSON body matching { "detail": "message" } or { "error": "message" }. Upstream provider errors are relayed verbatim.
Status codes
| Status | Meaning | Retry? |
|---|---|---|
200 | Success. Request compressed and forwarded. | — |
400 | Invalid request body, missing required header (e.g. X-Provider-Key), or malformed JSON. | No — fix the request. |
401 | Missing, malformed, or revoked Authorization header. | No — check your API key. |
403 | Accessing a resource that doesn't belong to your account (e.g. PATCHing another user's key). | No. |
404 | Resource not found (unknown key ID, unknown endpoint). | No. |
422 | Pydantic validation failure — a field has the wrong type or is missing. | No. |
429 | Rate limit hit, or monthly token quota exceeded. Body tells you which. Headers include X-Mintoken-Tokens-Used and X-Mintoken-Tokens-Limit. | Yes — after backoff. For quota, upgrade instead of retrying. |
500 | Internal mintoken error. Rare; shouldn't happen. | Yes — with exponential backoff. |
502 | Upstream provider returned an unparseable response or the connection dropped. | Yes. |
503 | Mintoken briefly unavailable (deploy, scaling event, free-tier cold start). | Yes — after 30s. |
504 | Upstream provider took more than 120 seconds to respond. | Yes. |
Recommended retry policy
Exponential backoff on 429, 500, 502, 503, 504 — starting at 1s, doubling up to 30s, with full jitter. Give up after 5 attempts. The OpenAI and Anthropic SDKs have this built in; if you're using them, you don't need to add anything.
Provider errors
When the upstream provider returns a 4xx or 5xx, mintoken passes it through with the original status and body. So if OpenAI says your key is rate-limited, you get OpenAI's rate-limit error; if Anthropic says your model doesn't exist, you get Anthropic's error. Your existing error handling logic for those providers keeps working.