← Volver a las guías

Fix 401, 402, 429, and 5xx API Failures Fast

Debug Failed API Requests Without Guesswork

An API failure is only useful when you turn its status code into a concrete next action. For AI integrations, start by logging the HTTP status, response body, request ID, model name, endpoint, timestamp, and a redacted version of request headers. Never log full API keys or user prompts containing sensitive data. Then work through the error class below instead of repeatedly retrying the same broken request.

1. Fix 401 Errors: Authentication Is Missing or Invalid

A 401 Unauthorized response means the server could not authenticate the request. The usual causes are a missing Authorization header, an expired or revoked key, a malformed Bearer token, or sending credentials to the wrong base URL.

• Confirm the request includes Authorization: Bearer YOUR_API_KEY, with no extra quotes, spaces, or environment-variable placeholders.
• Check that your deployment environment actually has the expected secret. Local .env files are not automatically available in containers, CI jobs, or serverless deployments.
• Verify the SDK client points to the intended provider endpoint. For 59API, use https://api.59api.com as the API base URL.
• Create a fresh key if you suspect a copied, rotated, or exposed key is no longer valid.
• Use curl with the same key and a minimal request to distinguish an application configuration issue from a provider issue.

Do not treat a 401 as a transient failure. Retrying it adds noise and can hide the real deployment mistake. Fix credentials first, then confirm the request succeeds before restoring normal traffic.

2. Handle 402 Errors: Check Balance, Billing, and Model Cost

A 402 Payment Required response generally means the request cannot be served under the current account balance or billing state. This matters with usage-based AI APIs because model pricing, input size, output length, and retries all affect the final cost.

• Check your available balance and recent usage before changing application code.
• Inspect the requested model and token limits. A large maximum output can make a request more expensive than expected.
• Set realistic output limits and avoid sending unnecessary chat history or duplicated system prompts.
• Prevent duplicate submissions by assigning idempotency keys where supported and disabling automatic retries for non-idempotent workflows.
• Alert on low balance before production traffic reaches a hard stop.

59API is useful here because it provides pay-as-you-go access to native official-quality Claude and GPT models at a low cost, without forcing a model downgrade. It supports Claude models including Opus, Sonnet, Haiku, and Fable, while remaining compatible with Claude Code, Codex, and OpenAI SDK workflows. That makes it easier to control spend without rewriting an existing integration.

3. Recover From 429 Errors: Back Off Intelligently

A 429 Too Many Requests response indicates a rate limit, concurrency limit, or quota threshold. A fast retry loop makes this worse by sending more pressure into an already constrained system.

• Read response headers and body fields for a retry-after value, reset time, or limit information.
• Use exponential backoff with jitter, such as waiting 1, 2, 4, and 8 seconds plus a small random delay.
• Cap retries and surface a useful fallback after the limit is reached.
• Queue background jobs, limit parallel requests, and deduplicate identical prompts before they reach the API.
• Separate interactive traffic from batch jobs so a large import cannot exhaust capacity needed by users.

For chat interfaces, show a clear retry state rather than silently failing. For batch systems, persist the failed job and its retry count so processing can resume safely after capacity returns.

4. Diagnose 5xx Errors: Confirm Whether the Failure Is Yours

A 5xx response means the request reached the service but could not be completed because of an upstream or server-side problem. Common examples include 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout.

• Capture the provider request ID, exact status, timestamp, model, and endpoint for support investigation.
• Retry only idempotent requests, using capped exponential backoff and jitter.
• Reduce oversized prompts, large file payloads, or extreme output limits that may contribute to timeouts.
• Set client-side connect and read timeouts deliberately; an unlimited timeout can exhaust application workers.
• Add a circuit breaker so a sustained outage does not cascade into a broader application failure.

Test a minimal request with the same model. If that succeeds, compare payload size, tool definitions, streaming settings, and timeout configuration. If it fails consistently, retain the request ID and check service status information before escalating.

5. Build a Better API Error Playbook

Classify errors in code: fix configuration for 401, notify or replenish funds for 402, queue and back off for 429, and retry cautiously for 5xx. Track each class separately in observability dashboards so authentication regressions do not disappear inside generic error totals. For developers who want compatible AI access with predictable pay-as-you-go pricing, sign up for 59API and point your existing OpenAI SDK, Codex, or Claude Code setup at its API base URL.

Precios · Docs