> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> Diagnose failures using HTTP status, error bodies, and request logs.

## Start with three sources

Record the HTTP status, `message` / `type` / `code` in the error body, and the request time, model ID, and response request identifier if supplied. Use these to find console request logs. Remove keys, cookies, and sensitive input before sharing diagnostics.

A typical OpenAI-compatible error looks like this. Gateways, upstream services, and reverse proxies can return different structures, plain text, or HTML:

```json theme={null}
{
  "error": {
    "message": "Example error message",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}
```

| Symptom | Next action |
| - | - |
| 400 | Check JSON, required fields, model capabilities, and parameter combinations; correct the request first |
| 401 / 403 | Check the key, account status, model permissions, and access restrictions; do not retry blindly |
| 404 / HTML | Verify the hostname, path prefix, endpoint, and resource ID |
| 429 | Distinguish frequency, concurrency, and quota restrictions from the error and logs; avoid unbounded retries |
| 500 / 502 / 503 / 504 | Check gateway and upstream status and whether execution already occurred before retrying |
| Disconnection / timeout | Check the network and timeout settings; local cancellation does not prove no server execution |
| HTTP 200 without a model list | Check `success: false` and `message`; model-list lookup failures may currently return 200 |
| HTTP 200 with unfinished output | Inspect Responses `status`, Chat `finish_reason`, and SSE terminal events |

Status codes can vary by upstream and deployment configuration. HTTP 200 alone does not prove application-level completion.

## Bound your retries

The SDK examples disable retries. Production retry policies should cap both attempts and total time and use exponential backoff with jitter. Honor `Retry-After` when provided. Fix permission and parameter errors first; resolve account quota problems before retrying.

Generation requests are not inherently idempotent. This specification does not promise `Idempotency-Key` support. Retrying after a timeout, interrupted stream, or 5xx may duplicate output or usage; inspect logs and application state first. Do not silently restart a generation after delivering partial text.

## Unavailable models

[List models](/en/api-reference/models) again with the same key, then check the exact model ID, protocol, group, and channel configuration. Avoid masking the problem by switching models arbitrarily; capabilities and pricing may differ.

[API coverage](/en/guides/api-coverage) · [Production integration](/en/guides/production) · [Troubleshooting](/en/guides/troubleshooting)

[简体中文](/zh/guides/errors)

[Model routing](/en/guides/model-routing) · [Rate limits](/en/guides/rate-limits) · [Observability](/en/guides/observability) · [AI SDK](/en/guides/ai-sdk)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.