Error Handling for AI APIs: Retries, Timeouts, and Safe Fallbacks

Error Handling for AI APIs: Retries, Timeouts, and Safe Fallbacks#

AI APIs fail in recognizable ways: timeouts, rate limits, invalid requests, provider outages, and malformed model output. Production clients should classify errors before retrying. Retry transient 429 and 5xx responses with exponential backoff and jitter; do not retry authentication or validation errors.

What Is This Approach?#

Official SDKs may offer basic retries, while a gateway can centralize routing and failover. Self-hosted stacks provide control but require health checks and dead-letter handling.

How to Implement It#

import time, random
from openai import OpenAI
client = OpenAI(base_url="https://crazyrouter.com/v1", api_key="YOUR_KEY")
for attempt in range(3):
    try:
        result = client.chat.completions.create(model="gpt-5-mini", messages=[{"role":"user","content":"Classify this ticket"}], timeout=15)
        break
    except Exception:
        if attempt == 2: raise
        time.sleep((2 ** attempt) + random.random())

Pricing Breakdown#

Prices and model availability change over time, so verify the current provider and Crazyrouter pricing before making a production forecast. Calculate effective cost per successful task, not only cost per token.

Production Checklist#

• Define a timeout and a bounded retry policy.
• Validate structured outputs and tool arguments outside the model.
• Record model, version, request ID, latency, token usage, and cost.
• Add tenant quotas, circuit breakers, and a human review path for high-impact actions.
• Keep prompts, schemas, and evaluation cases versioned.

A Practical Rollout Plan#

Start with a thin vertical slice instead of abstracting every provider feature on day one. Pick one user journey, one primary model, and one fallback. Capture a small set of representative requests, including short prompts, long context, malformed input, empty results, and adversarial instructions. This gives you a baseline before optimization changes the behavior you are measuring.

Next, put policy decisions outside the model. Authentication, tenant permissions, tool authorization, spending limits, and data retention should be enforced by application code. The model may suggest an action, but it should not decide whether the current user is allowed to perform it. This separation makes security reviews and incident investigations much easier.

For reliability, make every request observable without storing raw sensitive content by default. A useful trace records a request ID, tenant ID, route, model version, latency, token counts, retry count, and final outcome. Hash prompts or store redacted summaries when full content is not required. Add dashboards for successful-task cost, p95 latency, schema-validation failures, and fallback frequency.

Finally, review the route on a schedule. Model providers change pricing, limits, and behavior. Re-run the evaluation set after provider updates, prompt edits, or routing changes. Keep a rollback route available and communicate limits honestly to users. This operating discipline usually saves more money than prematurely optimizing a few cents of token cost.

Frequently Asked Questions#

Why do AI API requests fail?#

Common causes include rate limits, timeouts, invalid parameters, provider incidents, and output validation failures.

How do I control AI API costs?#

Track usage by tenant, cap output tokens, cache repeat work, route by task, and alert on budget anomalies.

Should every provider share one interface?#

Share a stable core, but preserve provider-specific extensions where they affect quality or product features.

What should a production benchmark measure?#

Quality, latency, error rate, schema validity, safety behavior, token usage, and cost per successful task.

Example Decision Matrix#

Before choosing an implementation, write down the workload’s quality bar, latency target, data sensitivity, and monthly volume. A customer-support draft may tolerate a fast small model and a short cache TTL; a financial reconciliation workflow may need deterministic tool calls, a stronger model, and human approval. This simple matrix prevents teams from choosing a model based only on a leaderboard or a single impressive demo.

For staged delivery, begin in shadow mode: send a small percentage of sanitized production-shaped traffic to the candidate route while keeping the existing response visible to users. Compare quality and latency, but also inspect failure categories and escalation frequency. Once the candidate is stable, expose it to a limited tenant cohort with a rollback flag. This turns provider changes into reversible deployments rather than risky migrations.

Summary#

Production AI engineering is measurement plus restraint: classify failures, cap work, preserve traceability, and test model changes against representative tasks. A unified route such as Crazyrouter can reduce integration overhead while your team builds evidence.