Proxy Errors and Retries

Applications should handle AISIX proxy failures in a consistent order: match the response format, decide whether retrying can help, then inspect route, policy, or upstream state when the failure persists.

This guide explains the client-side handling model. It does not replace the full Headers and Error Codes reference, which lists exact envelopes, headers, and status-code mappings.

Match the Response Format

Start by matching the response to the proxy route your application called. This tells the client which error fields to read before it decides whether to fix the request, back off, or retry.

Route family	Error format	Client handling
OpenAI-compatible routes, including chat completions, embeddings, responses, audio, images, and rerank	OpenAI-style error envelope	Read the OpenAI-style error type and optional error code.
Anthropic-style routes, including Messages and Count Tokens	Anthropic-style error envelope	Read the Anthropic-style error type.
Provider passthrough routes	Upstream provider status and body	Use the provider's native error handling after AISIX authenticates the caller and resolves the provider target.

Keep proxy and admin error handling separate. The Admin API has its own error format and is meant for management clients, not application traffic.

Decide Whether Retrying Helps

After the client knows which response format it received, use the error type as the main decision signal. The status code gives the broad class, but the error type usually tells you what the application should do next.

Failure class	Typical cause	Retry guidance
Caller or configuration error	The caller API key, model alias, access rule, request body, or endpoint choice is invalid.	Do not retry until the request or gateway configuration changes.
Policy rejection	A guardrail, rate limit, or budget check rejected the request.	Back off when the response includes a retry hint; otherwise change the request or policy.
Unsupported route	The resolved provider adapter does not implement the requested endpoint.	Choose a supported endpoint, provider, adapter, or model.
Upstream failure	The upstream provider returned an error that AISIX rendered through the caller-facing format.	Retry only when the failure is transient and the request is safe to repeat.
Runtime target state	The selected target, or every routing candidate, is temporarily unavailable.	Honor the retry hint when present and check provider health if the condition persists.

Treat authentication, authorization, model-not-found, invalid-request, and unsupported-route errors as non-retryable. Treat rate limits, budget denials with a retry hint, upstream transient failures, and unavailable routing candidates as conditionally retryable.

Use Retry Signals

AISIX can return Retry-After for gateway rate limits, budget denials, temporarily unavailable routing candidates, and upstream rate-limit responses that include a retry hint.

When the header is present, use it as the primary delay. If the client SDK also has automatic retries, prefer the delay from AISIX or the upstream provider over a fixed local interval.

Streaming changes the retry decision. A streaming request can fail before the stream starts, but AISIX does not fail over after a stream has started. Only retry a streaming request when the application can safely replay the prompt and handle duplicate output risk.

Understand Upstream Failures

Some failures come from AISIX before an upstream call is made. Others come from the selected upstream provider and are rendered through the caller-facing proxy format.

For upstream 4xx failures, AISIX keeps the response in the caller-facing format. On OpenAI-style routes, cross-provider upstream failures use a stable upstream-error type and may include a more specific code, such as a rate-limit, permission, or model-not-found code. Native OpenAI upstream failures can keep more OpenAI-style error fields.

For upstream 5xx failures, AISIX generally returns a 502 response and does not expose the upstream response body. Upstream server errors can contain provider account, infrastructure, or internal diagnostic detail, so use gateway logs for deeper diagnosis.

Check Common Causes

Use these checks to decide whether the failure starts in the caller request, gateway configuration, policy, routing state, or upstream provider.

Symptom	Check
Authentication failure	Confirm the application sends the plaintext caller API key, not the stored key hash or upstream provider key.
Permission failure	Confirm the caller API key allows the requested model alias.
Model not found	Confirm the application sends the caller-facing model alias, not the upstream provider model ID.
Rate-limit or budget rejection	Check caller-key limits, model limits, matching rate-limit policies, and managed budget state.
Unsupported endpoint	Confirm the selected provider and adapter support the route the application called.
502 response on one model alias	Check the upstream provider path, provider credential, base URL, and upstream provider availability for that alias.
All routing candidates unavailable	Check target model runtime status and provider health for the multi-target model.

Next Steps

You have now seen how to classify AISIX proxy errors and retry signals. For exact envelopes, headers, and status mappings, see Headers and Error Codes. For provider and endpoint support, see Provider Compatibility.