← Voltar aos guias

API Errors Demystified: 401, 402, 429 and 5xx

Debugging Failed API Requests: Myths vs. Facts

When an API request fails, the status code is evidence, not a complete diagnosis. A 401, 402, 429, or 5xx response can look like an application bug, but each code points to a different layer: credentials, account balance, traffic control, or service availability. Treating them all with the same retry loop wastes time and can make the failure worse.

Myth: A 401 always means the API key is invalid

Fact: A 401 Unauthorized response means the server could not authenticate the request as submitted. An invalid key is one cause, but formatting and environment mistakes are just as common.

First, confirm the application is reading the expected secret. Print only a masked prefix and key length in a secure development environment; do not log the full token. Check for an old shell variable, a missing deployment secret, trailing whitespace, or a key copied with quotation marks. Then verify the authorization format required by the provider or SDK. For OpenAI-compatible clients, this is commonly an Authorization header with a Bearer token. A request sent to the wrong base URL can also produce a confusing authentication failure.

For 59API, ensure your client targets https://api.59api.com and that the configured API key belongs to the intended account. Because 59API is compatible with OpenAI SDK workflows as well as Claude Code and Codex, a common migration issue is changing the key but leaving a previous provider endpoint in configuration. Test one minimal request outside your application to separate credential problems from application logic.

Myth: A 402 is a temporary server outage

Fact: A 402 Payment Required response generally means the request cannot be funded under the account's current billing state. Retrying the same request without changing anything is unlikely to help.

Check the account balance, payment status, and any project-level spend limits before investigating the model or prompt. For usage-priced AI APIs, consider whether a long context, a high output-token limit, or concurrent requests consumed available funds faster than expected. Record the model name, estimated input size, maximum output setting, and request timestamp alongside the failure. Those fields make a billing issue actionable.

Cost control is also a debugging tool. 59API provides pay-as-you-go access to native official-quality Claude models, including Opus, Sonnet, Haiku, and Fable, plus GPT models, without a model-quality downgrade. Its low relay pricing helps teams test and operate workloads economically, but applications should still set sensible token caps and alert before balances become critical.

Myth: The right response to 429 is to retry immediately

Fact: A 429 Too Many Requests response means the API is protecting a rate, concurrency, or quota boundary. Fast retries increase pressure and often keep the client rate-limited.

Inspect the response headers and body for a retry interval or rate-limit metadata. Honor a Retry-After value when present. Otherwise, use exponential backoff with jitter: wait briefly, increase the delay after each failed attempt, and add a small random value so many workers do not retry at once. Put a maximum attempt count and a total retry deadline around the operation.

• Queue bursty jobs instead of launching every request simultaneously.
• Limit per-user and per-worker concurrency.
• Cache stable responses and deduplicate identical in-flight requests.
• Use idempotency protections for operations that must not execute twice.
• Reduce unnecessary calls by batching only where the API supports it.

Measure 429s by endpoint, model, account, and deployment version. A sudden increase after a release often reveals an accidental loop, duplicate event delivery, or an overly aggressive worker count.

Myth: Every 5xx error is the provider's fault

Fact: A 5xx response indicates a server-side failure, but the triggering condition may still be a malformed edge case, a timeout in your network path, or an unsupported request pattern. Preserve the response body, request ID, timestamp, endpoint, model, and a redacted payload summary. These details let support teams correlate the event without exposing credentials or sensitive prompts.

Retry transient 500, 502, 503, and 504 failures with bounded exponential backoff. Do not retry indefinitely, and do not automatically retry requests that could create duplicate side effects. Configure connect and read timeouts separately, use a circuit breaker when failures persist, and provide a clear fallback in user-facing applications. For generative AI, that might mean queueing the work, selecting an approved alternative model, or asking the user to try again later.

A Practical Failure Workflow

Classify the status code first, then capture request metadata, validate configuration, and apply the matching recovery strategy. Test a minimal reproducible request before changing several variables at once. This turns API debugging from guesswork into a short investigation with evidence.

For developers seeking an economical relay while keeping official-quality Claude and GPT model access, 59API is a practical option to evaluate. Create an account when you are ready to test your existing compatible client against its pay-as-you-go endpoint; its referral rebate can further reduce qualifying usage costs.

Preços · Docs