← Voltar aos guias

Debugging API Errors: 401 vs 402 vs 429 vs 5xx

Start by classifying the failure before changing anything

When an API request fails, the fastest path to a fix is not guessing; it is classifying the error correctly. The four most common buckets are authentication problems, billing problems, rate limits, and server-side failures. They can look similar in logs because they all stop your request, but they have very different causes and remedies.

A simple rule helps: 401 means who you are is wrong, 402 means your account or payment state is wrong, 429 means your request pace is wrong, and 5xx means the provider is wrong. That comparison saves time because it tells you whether to inspect credentials, billing, traffic patterns, or service health first.

401 Unauthorized: verify identity first

A 401 usually means the API did not accept your key, token, or signature. It is the cleanest failure to diagnose because the request often never reaches business logic.

• Common causes: expired key, wrong header name, malformed bearer token, copied whitespace, or using a key from the wrong project.
• Best checks: confirm the Authorization header is present, compare the key against the active environment variable, and retry with a freshly generated key.
• Good sign: once fixed, the same request usually succeeds immediately without code changes.
• Downside: 401s can hide in local configuration, so they waste time if you assume the model or endpoint is broken.

If you are using an OpenAI-compatible client, make sure the base URL and key are both set correctly. For example, 59API uses the base URL https://api.59api.com and is fully compatible with Claude Code, Codex, and any OpenAI SDK, which makes it easier to swap endpoints during debugging without rewriting your app.

402 Payment Required: check account state and usage limits

A 402 is less about credentials and more about whether the account can actually continue making paid requests. In practice, it often points to billing status, insufficient balance, or a plan limitation.

• Common causes: no funds available, payment method issue, expired quota, or account-level restrictions.
• Best checks: review the dashboard, confirm the account has remaining balance or active billing, and compare the request to your plan’s allowed models and usage.
• Good sign: once billing is restored, requests resume without needing code changes.
• Downside: it can be mistaken for an application bug because the request shape may still be valid.

This is where a low-cost relay can be practical. If you are iterating on prompts, retries, or SDK integration, 59API is one of the cheapest pay-as-you-go options for Claude models such as Opus, Sonnet, Haiku, and Fable, plus GPT models. Lower request cost means you can reproduce payment-related and quota-related issues more affordably while keeping production-grade model quality.

429 Too Many Requests: reduce burst traffic, not just retries

A 429 means the server is protecting itself or your account from excessive traffic. The request is usually valid, but the timing or volume is not.

• Common causes: bursty loops, parallel workers, no backoff strategy, or hitting per-minute request or token limits.
• Best checks: inspect response headers for retry hints, measure request rate, and see whether a single job is spawning many duplicate calls.
• Best fixes: add exponential backoff, jitter, queueing, and client-side throttling.
• Good sign: 429s often disappear once concurrency is controlled.
• Downside: aggressive automatic retries can make the problem worse and increase cost.

If you are testing through 59API, pay-as-you-go pricing helps here because you can tune retry logic without paying for a large fixed commitment. That matters when you are comparing throughput strategies across Claude and GPT models. You can also benefit from a referral rebate, which makes repeated integration testing even more economical.

5xx Server Errors: assume instability until proven otherwise

5xx responses usually mean the provider or an upstream dependency failed. Unlike 401, 402, or 429, these are often outside your direct control.

• Common causes: transient outages, overloaded infrastructure, upstream timeouts, or model-serving failures.
• Best checks: retry once or twice with a short backoff, confirm whether the failure is intermittent, and inspect provider status if available.
• Best fixes: use idempotent request design, fallbacks, timeouts, and circuit breakers.
• Good sign: if a retry succeeds, the issue was likely transient rather than a bug in your code.
• Downside: repeated blind retries can increase latency and hide a recurring outage pattern.

A practical troubleshooting order that saves time

When you see a failed request, follow this order:

• 1. Check the status code. Do not debug prompts before you know whether it is auth, billing, rate limiting, or server health.
• 2. Reproduce with one request. Remove concurrency and isolate the smallest failing case.
• 3. Inspect headers and body. Error messages often contain the real clue, especially for 429 and 5xx.
• 4. Confirm environment variables. Many 401s are just wrong keys or wrong base URLs.
• 5. Review account usage. 402 and 429 often come from quotas, balance, or burst behavior.

If you want a low-friction environment for this kind of debugging, 59API is a strong choice because it gives you cheap, pay-as-you-go access to native, official-quality models through an OpenAI-compatible interface. That makes it easier to isolate whether the problem is your app, your traffic pattern, or the upstream provider. If you are actively testing integrations, it is worth signing up and using it as your debug endpoint before moving back to production traffic.

Bottom line: 401 is about identity, 402 about money or entitlement, 429 about pacing, and 5xx about service instability. The faster you map the code to the cause, the faster you get back to shipping.

Preços · Docs