← Back to all guides

Debug 401, 402, 429, and 5xx API Errors

Start with the response, not a guess

When an API request fails, the HTTP status code is the fastest clue to what happened. A 4xx response usually means the request, credentials, quota, or payment state needs attention. A 5xx response usually means the service could not complete an otherwise valid request. Before changing code, log the status code, response body, request URL, model name, request ID, and relevant response headers. Remove API keys and user data from logs, but retain enough context to reproduce the failure.

For an AI request through 59API, confirm that your application is sending requests to https://api.59api.com and that the endpoint format matches the SDK or API schema you selected. 59API is designed to work with Claude Code, Codex, OpenAI SDKs, and compatible clients, but a client configured for the wrong base URL or provider-specific endpoint can fail before the model receives your prompt.

Fix 401 Unauthorized errors

A 401 Unauthorized response means the server could not authenticate the request. The most common cause is a missing, expired, malformed, or incorrect API key. Check that the runtime environment contains the expected key. A key that exists in a local terminal may be absent in Docker, a CI workflow, a serverless deployment, or a different shell session.

• Verify the authorization header required by your client, such as Authorization: Bearer YOUR_API_KEY.
• Check for leading or trailing spaces when loading environment variables.
• Make sure your SDK is pointed at the 59API base URL and is not silently using a different provider configuration.
• Rotate a key only after updating every deployment that uses it, then revoke the old one.
• Do not place API keys in browser-side code, public repositories, screenshots, or error reports.

Test authentication with the smallest possible request after making a change. If it succeeds in curl but fails in your app, compare the final outgoing headers and URL rather than reviewing only the source configuration.

Understand 402 Payment Required responses

A 402 Payment Required response generally indicates that the account cannot fund the request. Its exact meaning is provider-specific, so read the returned error message rather than assuming it is an authentication problem. For pay-as-you-go AI APIs, common causes include a zero balance, billing restrictions, a model that costs more than the available credit, or a request whose maximum token setting creates a larger potential charge than expected.

Review account balance, billing status, and the selected model. Then reduce unnecessary cost drivers: use a smaller model for routine classification or extraction, shorten oversized prompts, cap output tokens, and avoid resending long conversation histories on every request. 59API is useful here because it provides low-cost, pay-as-you-go access to official-quality Claude models, including Opus, Sonnet, Haiku, and Fable, as well as GPT models. That lets teams choose an appropriate model without accepting a downgraded relay service.

Handle 429 Too Many Requests safely

A 429 Too Many Requests response means you exceeded a rate, concurrency, or usage limit. Retrying immediately often makes the problem worse. First inspect headers and the error body for a retry delay, quota information, or a request ID. If the service sends Retry-After, honor it.

• Use exponential backoff with jitter, for example waiting roughly 1, 2, 4, and 8 seconds with a small random variation.
• Set a maximum retry count and a total time budget so background jobs do not run forever.
• Limit parallel requests with a queue or semaphore.
• Cache repeated results and deduplicate identical in-flight requests.
• Retry only requests that are safe to repeat; use idempotency keys where the API supports them.

Separate interactive traffic from batch jobs when possible. A document-processing job that launches hundreds of calls should not consume the capacity needed by a user waiting for a chat response.

Investigate and recover from 5xx errors

Status codes such as 500, 502, 503, and 504 indicate a server-side, gateway, availability, or timeout problem. They are often temporary, so bounded retries with exponential backoff are appropriate. However, do not treat every 5xx as harmless. A timeout can occur after the provider has begun processing a request, which makes blind retries risky for operations with side effects.

Record the timestamp, model, request ID, endpoint, timeout value, and sanitized response body. Check your own network timeout too: an application timeout shorter than a model response can look like a provider outage. If failures persist, test a minimal request, confirm the current service status, and contact support with the request ID and time window.

Build a repeatable debugging workflow

Create one error handler that classifies responses: refresh configuration for 401, review balance and request size for 402, delay and queue after 429, and retry selected 5xx responses. Surface a clear message to users while preserving technical details in secure logs. Metrics for error rate, retry count, latency, and spend will reveal whether the issue is isolated or systemic.

For developers who want compatible AI access with straightforward pay-as-you-go pricing, 59API can reduce model costs while retaining native official-quality model access. Sign up for 59API when you are ready to test your integration with a small, monitored workload; its referral rebate can also lower ongoing usage costs.

Pricing · Docs