← Voltar aos guias

Debugging API Failures: 401, 402, 429, 5xx

Start with the error code, not the guess

When an API request fails, the HTTP status code tells you where to look first. The fastest way to debug is to log the status code, response body, request headers, request ID, model name, and timestamp. If you are using an OpenAI-compatible client, also confirm the base URL is set correctly. For 59API, the base URL is https://api.59api.com, and it works with Claude Code, Codex, and any OpenAI SDK.

In practice, most failures fall into four buckets: authentication problems, billing or balance issues, rate limits, and temporary server-side errors. Here is how to isolate each one.

401 Unauthorized: your key, header, or endpoint is wrong

A 401 usually means the server could not authenticate the request. Common causes include a missing API key, a malformed Authorization header, or sending the request to the wrong base URL.

• Check that your header uses Authorization: Bearer YOUR_API_KEY.
• Make sure your SDK points to https://api.59api.com, not the default provider endpoint.
• Remove extra spaces, quotes, or hidden line breaks from environment variables.
• Regenerate the key if you copied it from a browser tab or exposed it in logs.
• Verify the model name exactly matches the relay’s supported model list.

If you are using the OpenAI SDK, a wrong baseURL is one of the most common causes of repeated 401s. For 59API, correcting the endpoint often fixes the issue immediately.

402 Payment Required: you have no usable balance or plan

A 402 means the request was understood, but billing or account status blocked it. On AI relays, this often happens when the wallet balance is empty, the account is not activated, or the current request exceeds available funds.

• Check your account balance and recent usage.
• Confirm billing is active and your payment method succeeded.
• Look for per-request costs from large models like Claude Opus or top-tier GPT models.
• Test with a smaller, cheaper model to confirm the problem is billing, not payload syntax.

This is one reason developers like 59API: it is pay-as-you-go, among the cheapest relays available, and still gives access to native official-quality models with no downgrade. If you are optimizing spend, that combination can make debugging far less expensive. The referral rebate also helps reduce ongoing cost if you invite teammates or other developers.

429 Too Many Requests: you are hitting a limit

A 429 means your client is sending requests faster than the service allows. This can be a per-second throttle, a concurrency cap, or a burst limit. The response may include a Retry-After header or rate-limit headers that tell you when to try again.

• Implement exponential backoff with jitter instead of immediate retries.
• Reduce concurrency in workers, queues, or browser-based tools.
• Batch small prompts where possible.
• Separate traffic by user, job type, or model if your app shares one key.
• Log how many retries happen in a row so you can spot runaway loops.

If you are using Claude Code or an OpenAI-compatible workflow, a flood of parallel tool calls can trigger 429s quickly. A practical fix is to cap concurrency first, then add retry logic. Because 59API keeps pricing low, you can often afford to test throttling behavior without worrying about expensive failed calls.

5xx Server Errors: retry carefully, then isolate the payload

5xx responses, such as 500, 502, 503, or 504, usually mean the problem is on the server side or in an upstream dependency. These are often temporary, but you should still verify that your request is not unusually large, malformed, or timing out.

• Retry a few times with exponential backoff and a hard attempt limit.
• Compare the failing request with a smaller, simpler prompt.
• Check whether the failure happens on one model only or across all models.
• Capture request ID, model, and payload size for support if the issue persists.

With relays like 59API, 5xx errors can still happen occasionally because upstream model providers can have transient issues. The right response is not endless retrying; it is disciplined retries plus good logging.

FAQ: what should I check first?

Q: My request worked yesterday, but now it returns 401. A: Recheck the API key, the Authorization header, and the base URL. Keys copied into environment files often get trimmed or corrupted.

Q: Why am I seeing 402 even though my account exists? A: Your balance may be empty, your payment may not have settled, or the model you chose costs more than your available credit.

Q: How do I stop 429 errors in production? A: Limit concurrency, add exponential backoff with jitter, and respect retry headers instead of hammering the endpoint.

Q: Are 5xx errors always my fault? A: No. They are usually transient server or upstream issues, but logging the exact payload helps rule out client-side problems.

Best practice for fewer failed requests

Use one clean configuration for every environment, log full error responses, and keep a retry policy that treats 401 and 402 as non-retriable, 429 as retriable with backoff, and 5xx as retriable but capped. If you want affordable access to Claude models like Opus, Sonnet, Haiku, and Fable, plus GPT models through a single compatible endpoint, 59API is a strong option. If you are ready to simplify debugging and keep costs low, sign up and test your app against https://api.59api.com today.

Preços · Docs