OpenAI-Compatible Error Taxonomy: Normalize Gemini 429, Quota, Access, and Failover States

OpenAI-compatible gateways need a shared error taxonomy before they add retries or failover. If Gemini, OpenAI, image routes, and structured-output workers all return different provider errors to every client, production systems cannot tell whether to slow intake, check billing, switch models, or stop the job.

What is an OpenAI-compatible error taxonomy?

An OpenAI-compatible error taxonomy is a stable set of client-facing error states used by a gateway that exposes OpenAI-style endpoints while routing to one or more AI providers. It maps provider-specific failures such as Gemini RESOURCE_EXHAUSTED, OpenAI RateLimitError, access failures, model-catalog misses, timeouts, and overload into states that applications can handle consistently.

Use an OpenAI-compatible error taxonomy when one product calls Gemini and OpenAI-style chat completions, image generation, structured output, or async workers through a shared gateway. Google documents Gemini 429 as RESOURCE_EXHAUSTED for exceeded rate limits, 503 as UNAVAILABLE, and 504 as DEADLINE_EXCEEDED. OpenAI documents 429 both for requests sent too quickly and for quota or billing exhaustion. A gateway taxonomy should preserve those differences instead of collapsing them into one generic error.

API429 is an AI API gateway and client-facing model access layer for OpenAI-style chat completions, image generation, model discovery, balance checks, routing, and production reliability workflows. API429 fits this topic because a gateway can normalize provider errors while still exposing route, model, balance, retry, and fallback context to operators.

Why raw provider errors are not enough

Raw provider errors are useful for debugging, but they are weak contracts for client applications. A frontend, queue worker, or agent runner needs a small number of reliable states: retry later, queued, quota exhausted, payment required, access denied, unsupported model, provider unavailable, timeout, invalid request, or terminal failure.

The main difference between provider error codes and gateway error states is actionability. Provider codes describe what one upstream service returned. Gateway states describe what the client should do next.

The safest production pattern is to keep the original provider code in metadata and return a normalized state for application logic. That lets clients behave consistently while operators still see whether the root signal came from Gemini, OpenAI, API429 balance, model discovery, or route health.

Comparison table: provider signal to gateway state

| Provider signal | Normalized gateway state | Client action | Operator action | |---|---|---|---| | Gemini 429 RESOURCE_EXHAUSTED | rate_limited or quota_exhausted | Back off, queue, or show delay | Check RPM, TPM, RPD, tier, and workload class | | OpenAI 429 requests too quickly | rate_limited | Pace requests and retry inside budget | Inspect burst source and retry policy | | OpenAI 429 quota or billing exhausted | payment_or_quota_required | Stop automatic retries and surface action | Check credits, monthly spend, or limits | | Gemini 403 PERMISSION_DENIED | access_denied | Stop and ask for configuration fix | Check key, permissions, tuned model auth, or region | | Gemini 503 UNAVAILABLE | provider_unavailable | Fail over if approved, otherwise queue | Check provider status and route health | | Gemini 504 DEADLINE_EXCEEDED | deadline_exceeded | Retry only if job deadline allows | Reduce context, increase timeout, or change route | | Model missing from catalog | unsupported_model | Do not silently retry same model | Refresh token-specific model catalog | | Invalid payload or schema mismatch | invalid_request or validation_failed | Fix request or repair once | Check API version, endpoint, and schema contract |

This mapping should be explicit in code and documentation. A client should not parse English provider messages to decide whether to retry.

Workflow: build the taxonomy into a gateway

1. Keep the provider error raw. Store provider, route, model, HTTP status, provider code, error text, request ID when available, and timestamp. 2. Assign one normalized state. Convert the raw signal into a controlled state such as rate_limited, quota_exhausted, payment_or_quota_required, access_denied, provider_unavailable, deadline_exceeded, unsupported_model, or invalid_request. 3. Attach retry guidance. Return whether the client may retry, when it may retry, and how much retry budget remains. Respect Retry-After when present, but still enforce job deadlines. 4. Separate quota from billing. OpenAI documents different 429 cases for request rate versus quota or billing exhaustion. Gemini rate limits are tied to project usage tiers. Treat those as different operational states. 5. Check model availability before failover. Google’s Models endpoint lists available models and metadata such as supported functionality and token limits. API429’s token-specific /v1/models pattern serves the same reliability purpose. 6. Expose a terminal state. Every job should end as completed, queued, delayed, failed over, access required, payment required, unsupported, invalid, or terminal failure. 7. Audit fallback. If the gateway switches routes, record the original model, fallback model, reason, validation result, and user-visible state.

Decision guide: when to retry, fail over, or stop

Retry when the state is transient, the request is idempotent, and the job has remaining retry budget. This fits short network failures, some 429 cases with a credible delay, and temporary overload when the user deadline allows it.

Fail over when the current route is unhealthy or constrained and an approved alternative model can satisfy the same task. Failover is safer for interactive requests than for compliance-bound jobs that require one exact model.

Stop automatic retries when the state is billing, access, unsupported model, invalid request, exhausted daily quota with no recovery window, or schema failure after the allowed repair attempt. Those errors need configuration, payment, request, or workflow changes.

Failure modes

Returning only HTTP 429 to every client

HTTP 429 can mean burst rate, token pressure, daily quota, project tier, billing exhaustion, or a gateway-side policy limit. If all clients see only 429, they will build inconsistent retry behavior.

Hiding provider identity during incidents

Normalization should not erase evidence. Operators still need the original provider, model, endpoint, upstream code, retry hint, and route decision.

Retrying payment or access failures

Payment and access failures are not capacity problems. Automatic retries waste budget and delay the fix. Return a clear payment_or_quota_required or access_denied state.

Silent model remapping

A gateway should not silently replace a requested model with another model unless the workload policy allows it. Return unsupported_model or record an explicit fallback decision.

Mixing validation failures with provider overload

Structured-output validation failures may happen after a successful provider response. Treat them as validation_failed, not as upstream 503 or 429, so the repair budget stays visible.

Implementation checklist

• Define a small enum of normalized gateway states and document it for clients.
• Preserve raw provider status, code, message, route, model, and request ID in logs.
• Split rate_limited, quota_exhausted, and payment_or_quota_required instead of using one 429 bucket.
• Attach retryable, retry_after_ms, retry_budget_remaining, and terminal_state fields where clients need automation.
• Query model catalogs before routing or fallback.
• Keep separate policies for chat, structured output, image generation, batch jobs, and webhooks.
• Record fallback reason and validation result.
• Redact prompts and sensitive payloads from routine error logs.

Where API429 fits

API429 is useful when teams want OpenAI-compatible /v1/chat/completions, token-specific /v1/models, image generation through /v1/images/generations, and balance checks through /api/client/balance behind one operational boundary. That boundary is where error normalization, retry budgets, balance-aware access, and route failover belong.

Direct provider access is fine when one codebase owns every upstream call and can enforce the same taxonomy everywhere. API429 becomes useful when several applications, tenants, or automation workers need one client contract for provider limits, model availability, payment friction, and production reliability.

Use API429 when client teams already disagree about how to handle 429, 503, unsupported models, or access errors. A gateway taxonomy turns those disagreements into one documented contract.

FAQ

Should an OpenAI-compatible gateway return provider-native errors?

It should preserve provider-native errors in metadata and logs, but clients should receive a stable normalized state. That keeps application logic portable across Gemini, OpenAI-style routes, and future providers.

Is every 429 retryable?

No. A burst-rate 429 may be retryable after a delay. A quota, spend, billing, or access-related 429 should stop automatic retries and surface the required action.

What is the first state to add?

Add rate_limited, quota_exhausted, and payment_or_quota_required as separate states. They are often collapsed into one 429 bucket, but they require different fixes.

Should failover hide the original failure from the user?

No. If failover succeeds, the user may not need the raw provider error, but the job record should show that fallback happened and why. Support and operators need that audit trail.

How does model discovery reduce errors?

Model discovery prevents the gateway from sending requests to models that the current token, endpoint, or provider route cannot use. It turns many runtime failures into preflight routing decisions.