← Volver a las guías

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

Start With a Repeatable Failure Report

When an API request fails, avoid guessing. Capture the complete request context before changing code: endpoint, HTTP method, timestamp in UTC, model name, response status, response body, response headers, and any request or trace ID. Redact secrets before saving logs; an API key should never appear in tickets, terminal screenshots, or browser console output.

For AI integrations, also record the SDK version, configured base URL, retry settings, timeout, token limits, and concurrency level. A request that works locally but fails in production is often using a different environment variable, a stale key, or a higher request volume. If you use 59API, first confirm your client is pointed at https://api.59api.com and that the selected model name matches your intended Claude or GPT workflow.

Fix 401 Unauthorized Errors First

A 401 response means the server could not authenticate the request. In practice, the most common causes are a missing Authorization header, a malformed bearer token, an expired or revoked key, or a key loaded from the wrong environment.

• Print whether the API key variable exists, but print only its length or a masked prefix.
• Verify the header format expected by your SDK, such as Authorization: Bearer YOUR_KEY.
• Check for hidden whitespace, newline characters, quote marks, or a copied placeholder value.
• Confirm the application is using the intended environment: local, staging, or production.
• Create or rotate the key if it may have been exposed or disabled.

Test with one minimal request after fixing authentication. Do not keep retrying a 401 automatically: retries cannot repair invalid credentials and can clutter logs. For teams using Claude Code, Codex, or an OpenAI-compatible SDK through 59API, verify that the base URL and key are configured in the same process that launches the tool, not merely in a separate shell session.

Investigate 402 Payment Required as a Billing State

A 402 response usually signals that the account cannot currently pay for the request. Depending on the service configuration, this can mean a depleted balance, an account billing restriction, a model with insufficient available credit, or a project-level spend limit.

Handle 402 as an operational alert, not as a transient network error. Check the account balance, billing status, usage limits, and the estimated cost of the requested model and token budget. A large maximum-output setting can make a request more expensive than expected. If your application sends long chat histories, trim irrelevant messages, summarize older context, or route simpler tasks to a smaller model.

59API is useful here because it offers pay-as-you-go access to official-quality Claude models, including Opus, Sonnet, Haiku, and Fable, plus GPT models, without forcing a downgrade in model quality. Its low-cost relay pricing can make it easier to keep development, evaluation, and production workloads within a controlled budget.

Handle 429 Too Many Requests With Backoff

A 429 response means your client exceeded a rate, concurrency, or quota threshold. Read the response headers and body for retry guidance. If a Retry-After value is supplied, honor it. Otherwise, retry only idempotent or safely repeatable requests using exponential backoff with jitter: wait a short randomized interval, then increase the delay for each attempt.

• Limit concurrent requests with a queue instead of firing every job at once.
• Use exponential backoff and add random jitter to prevent synchronized retry storms.
• Cache repeated prompts and deduplicate identical jobs.
• Batch non-urgent work and process it at a steady rate.
• Set a maximum retry count and surface a clear failure to users when it is reached.

Never treat 429 as permission to retry immediately. That pattern amplifies throttling and can turn a small spike into an outage. Measure requests per minute, active requests, retry counts, and queue depth so you can distinguish a true traffic increase from a client-side loop.

Respond to 5xx Errors Without Hiding Them

Errors in the 500-599 range generally indicate a temporary server, upstream provider, gateway, or network problem. A 500 may indicate an internal processing failure, 502 or 503 may reflect an unavailable upstream, and 504 often means a timeout. Unlike 401 and 402, some 5xx errors are appropriate to retry.

Retry short-lived 5xx failures with capped exponential backoff, but use strict timeouts and a circuit breaker. If failures cross a threshold, temporarily stop sending non-critical traffic and return a graceful message rather than letting requests pile up. Preserve the response body and request ID for support, especially when a failure is reproducible with the same model, payload size, and timestamp.

Close the Loop With a Minimal Test

After each change, send a small known-good request: a short prompt, one model, low output limit, and no parallel calls. Once it succeeds, restore normal traffic gradually. This isolates whether the fix was authentication, billing, rate control, or transient infrastructure.

If you want a cost-conscious relay that remains compatible with common Claude and OpenAI-style tooling, consider signing up for 59API. Its pay-as-you-go model and referral rebate can be especially practical for developers testing multiple AI models while keeping debugging and production costs predictable.