← Retour aux guides

LLM API Errors: A 10-Minute Debugging Playbook

Most LLM API failures come from a small set of problems: incorrect credentials, mismatched endpoints, invalid payloads, rate limits, or interrupted connections. Start with the HTTP status and response body—not random changes to your prompt. This quick-start guide helps you identify the cause, apply the smallest fix, and avoid expensive retries.

First minute: capture a useful failure report

Reproduce the error with one short text prompt, one request, and streaming disabled. Remove tools, images, and optional parameters until the simplest request works.

• Record: HTTP status, error type, sanitized error message, timestamp, requested model ID, latency, and request ID if available.
• Check routing: confirm the host, endpoint path, and SDK configuration. For 59API, the API host is https://api.59api.com. Copy the documented SDK base path exactly; missing or duplicated /v1 segments can cause failures.
• Protect secrets: never log authorization headers, API keys, or sensitive prompt content.

401 or 403: fix authentication and access

A 401 usually indicates missing or invalid credentials. Verify that your application actually loads the intended environment variable, removes accidental whitespace, and sends the authentication header required by the endpoint. OpenAI-compatible endpoints typically use Authorization: Bearer followed by the key; other API formats can require different headers.

A 403 usually points to an access restriction. Check account permissions, model access, IP restrictions, and any organization or project settings. When switching providers, replace both the base URL and credentials: a key issued by one service generally will not authenticate against another.

400, 404, or 422: inspect the request contract

Read the error body before editing anything. These statuses commonly indicate malformed input, an unavailable route, or an unsupported model or parameter, although exact meanings vary by service.

• Model: copy the exact API model identifier from the provider's model listing or documentation. Display names such as Claude Sonnet 5.5 or GPT-6.1 Sol are not necessarily request IDs.
• Payload: verify valid JSON, required fields, message roles, tool-result pairing, and the expected image or audio format.
• Parameters: remove optional sampling, structured-output, or tool settings that the selected model might not support.
• Context: reduce conversation history and retrieved documents if the input plus requested output exceeds the context budget. Leave room for generation.

SDK compatibility does not guarantee that every model supports every feature. Reintroduce optional fields one at a time after the minimal request succeeds.

429: distinguish throttling from exhausted quota

A 429 can mean requests-per-minute throttling, token throughput limits, or insufficient quota. Inspect the error code and billing dashboard. Adding retries will not fix an empty balance.

For temporary throttling, honor Retry-After when present. Otherwise, use exponential backoff with random jitter, a maximum delay, and a small retry budget. Queue requests and lower concurrency rather than letting every worker retry simultaneously. Check whether your SDK already retries automatically to avoid multiplying attempts through nested retry loops.

5xx and timeouts: retry carefully

Server errors and network failures are often transient. Retry eligible failures with bounded backoff, but investigate persistent errors using the request ID and timestamp. Configure connection and read timeouts separately where your client supports them; long generations may need a longer read window.

A timeout does not prove the request failed upstream. The model may still be generating, so a retry can create duplicate work and charges. Do not assume generation requests are idempotent. Use documented idempotency or request-status features only when the endpoint supports them.

200 OK, but the answer is incomplete

Inspect the finish reason and usage fields. An output-limit finish reason suggests increasing the supported output budget or requesting a shorter answer. A refusal requires revising the task, not blind retries.

For streaming, parse complete server-sent events rather than treating network chunks as JSON objects. Handle error events and premature disconnects; receiving HTTP 200 does not guarantee the entire generation completed.

Keep debugging affordable with 59API

59API offers low-cost, pay-as-you-go access to native official-quality models without downgrades, with OpenAI SDK compatibility and support for Claude Code, Codex, and Gemini CLI. That makes small, controlled integration tests practical across providers. Sign up for 59API when you are ready to test your minimal request, and check its referral rebate for additional savings.

Tarifs · Docs