← Voltar aos guias

Failed AI API Requests: A 10-Minute Debugging Guide

Start with evidence, not another retry

A failed AI API request usually points to one of four problems: authentication, billing, throttling, or service availability. The fastest fix is to capture the response before changing your code.

For one failing request, record the HTTP status, sanitized error body, UTC timestamp, elapsed time, model identifier, and request ID if returned. Inspect response headers, especially Retry-After. Never log API keys, authorization headers, or sensitive prompts.

With 59API, the API base URL is https://api.59api.com. Check your client's final request URL: some SDKs append endpoint paths automatically. A duplicated or missing version prefix can send a valid request to the wrong route. Confirm the documented endpoint instead of randomly adding or removing path segments.

401: Check the credentials actually being sent

A 401 normally means authentication failed. Before generating another key, verify the running process has the intended credential.

• Check for an unset environment variable, trailing newline, copied quotation marks, or a stale secret in your deployment.
• Match the authentication format to the endpoint. OpenAI-compatible endpoints commonly use Authorization: Bearer; other interfaces can require different headers.
• Use your 59API credential when calling 59API, not a key issued by an upstream model provider.
• After rotating a secret, restart or redeploy workers that loaded the old value at startup.

Reproduce the failure outside your application with a minimal request to the same documented endpoint. If that succeeds, inspect SDK configuration, proxy behavior, and environment-variable precedence. Repeated retries will not repair invalid credentials.

402: Verify balance and billing state

A 402 often indicates a payment or credit problem, but its exact meaning is service-specific. Read the error body and check your account dashboard for available balance, payment status, and any spending restrictions.

If you recently topped up, confirm the payment completed and the request uses the intended account's key. Avoid automatic retry loops until billing is resolved. Test recovery with a short prompt and a small output-token limit; a successful dashboard payment alone does not prove the application has switched to the correct account.

429: Separate request limits from token limits

A 429 means you need to understand the limiting dimension. Depending on the service, the bottleneck may be requests per minute, token throughput, concurrency, or a quota. The response body may distinguish them.

• For request-rate limits, queue work and smooth bursts rather than launching everything simultaneously.
• For token limits, shorten context and reduce requested output length where appropriate.
• For concurrency limits, use a shared semaphore or worker queue across processes, not just a per-request delay.

Honor Retry-After when supplied; it can be a delay in seconds or an HTTP date. If the error describes an exhausted quota rather than temporary throttling, resolve that condition instead of retrying indefinitely.

5xx: Isolate transient failures from repeatable ones

500, 502, 503, and 504 are server-side error responses, not proof that your payload is correct. A gateway timeout may hide a slow upstream operation; a repeatable 500 may expose an edge case triggered by your input.

Try a smaller, non-streaming request with the same model. Check service notices if available. If your application supports it, test another available model, such as Claude Sonnet 5.5 or Qwen3.7 Plus, using its documented API identifier rather than assuming the display name is accepted.

If failures persist, send support the timestamp, request ID, endpoint, and sanitized error. Avoid sharing credentials or private conversation content.

Use a bounded retry policy

For temporary 429s and selected transient 5xx failures, allow at most four total attempts within a 30-second overall deadline. Without Retry-After, use randomized exponential backoff: choose a delay between zero and the smaller of eight seconds or 0.5 × 2^n seconds, with n starting at zero. When Retry-After is present, do not retry sooner; stop if the wait exceeds your deadline.

Check existing SDK retries to avoid multiplying attempts. Retrying a timeout or interrupted stream can duplicate generation and charges; do not assume idempotency unless documented. Never silently replay a partially delivered answer.

Keep debugging affordable

59API combines low-cost, pay-as-you-go access with native official-quality models without downgrades and compatibility with OpenAI SDKs and popular coding clients. Small diagnostic requests keep troubleshooting inexpensive. If you want a budget-friendly relay for your next integration, consider signing up for 59API.

Preços · Docs