← Voltar aos guias

API Request Failed? Fix 401, 402, 429 and 5xx Fast

A failed AI API request does not always mean the model is unavailable. Authentication, account balance, traffic limits and upstream failures require different fixes. Start with the HTTP status and error body—not repeated retries. This quick-start guide helps you isolate the problem without wasting tokens or hiding the original failure.

First: capture one clean failure

Send one small, non-streaming request with a model available to your account and a short output limit. Temporarily remove tools, attachments and parallel calls. Record the following before changing anything:

• Request details: timestamp, HTTP method, endpoint, model identifier and client timeout.
• Response details: status, error type or code, message, request ID and any Retry-After or rate-limit headers.
• Routing details: SDK base URL, proxy settings and deployment environment.

Never log API keys, Authorization headers or sensitive prompts. If your SDK hides the response, inspect its exception’s status, headers and response body. A request with no HTTP response is a connection, DNS, TLS or timeout problem—not automatically a 5xx error.

401 Unauthorized: verify the credential path

A 401 usually means credentials are missing, invalid, expired or inappropriate for the endpoint. Confirm that the running process actually received the expected environment variable; updating a local shell does not update an already-running container or serverless deployment.

• Check for surrounding quotes, trailing whitespace and accidentally copied placeholder values.
• Use the authentication format required by your integration. OpenAI-compatible requests typically use Authorization: Bearer followed by the key; Anthropic-compatible integrations may require different headers.
• Match the key to its provider. A relay key belongs on the relay endpoint, not the model vendor’s endpoint.

For 59API, the service root is https://api.59api.com. Check the integration’s documented base URL: some clients expect a /v1 suffix, while others append it. Avoid duplicated path segments. Do not retry an unchanged 401; correct the configuration first.

402 Payment Required: check account funding

Many AI services use 402 for insufficient credit or billing restrictions, but its meaning is provider-specific. Read the error body and check the account dashboard for balance, payment status, project budgets and spending caps.

After adding credit or changing a limit, send one small test request. A successful payment does not necessarily mean the request is using the funded account: verify the key’s project or workspace. Blind retries cannot repair a billing block.

429 Too Many Requests: identify the exhausted limit

A 429 can reflect requests per minute, tokens per minute, concurrent requests or an account quota. Check the error code and available headers before assuming a short wait will fix it. A hard quota requires a limit or billing change.

• Slow the producer: queue requests and reduce worker concurrency.
• Reduce token pressure: shorten prompts and lower requested output limits when appropriate.
• Retry with bounds: honor Retry-After when present; it can contain seconds or an HTTP date.

Without retry guidance, use exponential backoff with jitter—for example, random delays capped at 1, 2, 4 and 8 seconds across four retries. Set an overall deadline, and check SDK retry defaults so application retries do not multiply hidden SDK attempts.

5xx Server Errors: retry selectively

500, 502, 503 and 504 often indicate temporary service or upstream trouble. Retry a small number of times with backoff, inspect the provider’s status information and retain request IDs for support. Not every 5xx is transient: 501 or 505 generally needs investigation rather than repetition.

A timeout or interrupted stream does not prove that generation stopped upstream. Retrying can duplicate work and charges. Do not automatically replay a stream after delivering partial text. Use idempotency only where documented, and protect any tool-triggered side effects separately.

Keep the baseline simple and affordable

59API is a low-cost, pay-as-you-go AI relay offering native, official-quality Claude and GPT models without downgrades, with compatibility for Claude Code, Codex and OpenAI SDKs. That makes it practical for small diagnostic requests and ongoing development. Its referral rebate offers another potential saving; check the current terms.

If you want an inexpensive integration baseline, sign up for 59API and validate one minimal request before adding concurrency. Keep that known-good test: it quickly separates application bugs from authentication, billing, throttling and upstream failures.

Preços · Docs