AI API Error Guide: 401, 403, 429 & 5xx
Diagnose AI API authentication, access policy, rate limits, client cancellation, and upstream failures, then decide when a retry is safe.
AI API errors are easiest to diagnose when the status code is treated as the beginning of an investigation, not the complete cause. Preserve the request ID, timestamp, endpoint, model, API key name, selected group, response body, and timing before retrying.
The goal is to identify which layer rejected or ended the request: client, authentication, access policy, protocol validation, routing, model backend, or downstream connection.
What common status codes usually indicate
| Status | First interpretation | First action |
|---|---|---|
400 | Invalid request shape, field, or protocol contract | Compare the payload with the selected endpoint; do not retry unchanged |
401 | Missing, malformed, disabled, expired, or invalid credential | Verify the Authorization header and the current key |
403 | Authenticated but blocked by account, model, group, IP, or policy | Check key restrictions and model/group access before testing channels |
404 | Wrong endpoint path or unavailable model identifier | Verify the base URL, path, and authenticated model list |
429 | Request-rate, quota, or eligible-route limit | Inspect quota and group limits; use bounded backoff or configured fallback |
499 | Downstream client disconnected or cancelled before completion | Inspect client deadlines, aborts, proxies, and first-output timing |
500 | Internal processing or adapter failure | Preserve the request ID; retry only if the operation is safe |
502/503 | Bad upstream response, unavailable route, or temporary capacity issue | Check route evidence and use bounded fallback or retry |
504 | A gateway or upstream time budget expired | Compare first-output and total timing with client deadlines |
These interpretations are diagnostic starting points. The error body and request record determine the actual reason for a specific call.
Diagnose 401 before changing the model
A 401 normally occurs before useful model routing. Check:
- the header uses
Authorization: Bearer ...; - the application did not include quotes, whitespace, or a placeholder value;
- the key is enabled and has not expired;
- the request is sent to the intended Modelflare host;
- a secret manager or deployment did not retain an older rotated key.
Do not paste the full key into logs or support messages. Reproduce with a dedicated test key if exposure is possible, then revoke the compromised credential.
Diagnose 403 as an access-policy failure first
A 403 does not automatically mean an upstream provider rejected the request. Authentication can succeed while access fails before channel selection because:
- the key restricts the requested model;
- the key's IP allowlist does not include the observed client IP;
- the account cannot use the selected model group;
- the user or key is disabled by policy;
- the requested feature is not allowed for that route.
Retrieve /v1/models with the same key, inspect its group and model limits, and compare the exact error code. If no channel was selected, changing upstream channels cannot fix the earlier policy decision.
Diagnose 429 without creating a retry storm
A 429 is a capacity or policy signal, not an instruction to retry immediately in a tight loop. Determine whether the limit belongs to the key quota, account, model group, or selected route.
For retryable rate limits:
- honor
Retry-Afterwhen present; - use exponential backoff with jitter;
- cap attempts and total elapsed time;
- keep application concurrency within a known bound;
- use ordered fallback groups only when they preserve the requested model and protocol.
Creating more API keys does not necessarily bypass an account- or group-level request limit.
Diagnose 499 from the caller outward
Modelflare can record 499 when the downstream client connection ends before the response completes. Start with the caller:
- Was an abort signal triggered?
- Did the client, load balancer, CDN, or reverse proxy reach an idle or total timeout?
- Did the user close the page or stop the agent?
- Did the stream produce a tool event without visible text?
- How long elapsed before first effective output?
A 499 record alone does not establish a channel outage. Compare other requests in the same time window and the same model/group before changing routing policy.
Separate 5xx failures by layer
For 5xx, preserve the original status and error details instead of converting every failure into a generic 500 in the client.
- A validation or adapter 500 can be deterministic and may fail again unchanged.
- A 502 can indicate an invalid or incomplete upstream response.
- A 503 can indicate no eligible route or temporary unavailability.
- A 504 indicates that a time budget expired, but the responsible layer still needs to be identified.
Use request timing, selected group, channel evidence available to support, and nearby requests to distinguish a single bad response from a sustained route issue.
Decide whether to retry
| Failure class | Default retry decision |
|---|---|
| Invalid payload or unsupported protocol | Fix the request; do not retry unchanged |
| Invalid key or denied access | Fix credentials or policy; do not retry unchanged |
| Quota exhausted | Increase or reallocate quota intentionally; do not loop |
| Rate limit | Retry with bounded backoff when permitted |
| Temporary 502/503/504 | Retry idempotent work with a strict attempt budget |
| Client cancellation | Retry only if the user still wants the work and duplicates are safe |
| Tool or write side effect | Require application-level idempotency before repeating |
Retries create new work and can create new cost. Record every attempt and avoid hiding the original failure behind a later success.
Evidence to capture safely
For support or incident review, capture:
- request ID and UTC timestamp;
- endpoint and streaming mode;
- requested model and selected group;
- HTTP status and structured error code;
- total time and first-effective-output time;
- whether the caller cancelled;
- a sanitized description of the request feature, such as tools or image input.
Do not include the full API key, prompt, response content, raw request body, email, or plaintext IP address unless an approved secure process specifically requires it.
After locating the failing layer, use Reliable AI API Routing for fallback design and the Streaming Guide for event and timeout failures.
Frequently asked questions
Does a 403 prove that a provider is down?
No. A 403 can be produced by account, key, model, group, IP, or feature policy before an upstream route is selected. Check the request record and error code first.
Is 499 a standard upstream model error?
No. In Modelflare request records it represents a downstream cancellation observed before completion. Investigate caller and proxy deadlines before treating it as model failure.
Should every 5xx response be retried?
No. Retry only operations that are safe to repeat, use a bounded attempt and time budget, and preserve the first error. Deterministic adapter or request problems will not improve with repetition.