Hypit troubleshooting: the errors you will actually hit
Four failure modes cover almost everything: authentication, credits, rate limits and upstream failures. Here is what each one means and what to do.
One error shape everywhere
Every route returns the same body: { "error": { "message", "type", "code", "param" } }. Branch on code (stable), log message (human-readable), ignore param (always null).
Status codes at a glance
401 authentication failed · 402 not enough credits · 413 payload too large · 425 identical idempotent request still preparing · 429 rate or concurrency limit · 499 caller went away · 500 our bug · 502 upstream failed · 503 no provider available · 504 upstream timed out.
Two limits per key
60 requests per minute, plus a cap on open jobs. Both are per API key, so a burst of parallel jobs hits the open-job limit before the request rate limit.
Step by step
1. 401 invalid_api_key
The key is missing, malformed or revoked. Send it as a bearer token; do not paste it into a query string.
2. 402 not enough credits
Not retryable in the same shape — it needs credits, not backoff. Check the remaining balance before retrying.
3. 429 rate or concurrency
Back off and retry. Batch work into fewer, longer jobs instead of many short parallel ones.
4. 503 no_available_provider
Retry with exponential backoff. This is our side being briefly unable to serve, not a bad request — do not rewrite your payload.
5. 504 upstream timeout
The vendor did not answer in time. Retry once; if it repeats, route that step to a different model or provider.
After this
If a failure returns credits, treat it as a signal about the request shape rather than about the model — most repeat failures are an unsupported parameter for that specific model.
Keep reading
FAQ
Are the error codes OpenAI-compatible?
The <code>type</code> field follows the OpenAI categories so existing client switches keep working; <code>code</code> is our own, more specific, stable value.
Why do I get a 425?
You sent an identical idempotent request while the first one was still being prepared. Wait briefly and reuse the same idempotency key.
Where are the full details?
The errors and limits reference lists every status, the two rate limits and how credits behave on failure.