# Mã lỗi

Định dạng lỗi chung và bảng mọi mã lỗi của API công khai.

Mọi response lỗi dạng JSON có cùng một shape, giống OpenAI:

```json
{
  "error": {
    "type": "insufficient_quota",
    "code": "insufficient_credit",
    "message": "Insufficient credit for this request.",
    "param": null
  }
}
```

- `code`: mã ổn định, chữ thường. **Rẽ nhánh theo field này.**
- `type`: nhóm lỗi (`invalid_request_error`, `authentication_error`, `permission_error`, `insufficient_quota`, `rate_limit_error`, `api_error`).
- `message`: mô tả cho người đọc, có thể thay đổi; đừng parse.
- `param`: field của request gây lỗi, nếu xác định được; ngược lại `null`.

Mỗi response có `x-request-id` (`req_...`); hãy gửi kèm khi liên hệ hỗ trợ.

## Bảng mã lỗi

Bảng dưới đây sinh tự động từ đặc tả OpenAPI ([`/openapi.public.yaml`](/openapi.public.yaml)), nên luôn khớp với API.

| code | status | type |
|---|---|---|
| `invalid_request` | 400 | invalid_request_error |
| `input_too_long` | 400 | invalid_request_error |
| `unauthorized` | 401 | authentication_error |
| `insufficient_credit` | 402 | insufficient_quota |
| `account_suspended` | 403 | permission_error |
| `not_found` | 404 | invalid_request_error |
| `model_not_found` | 404 | invalid_request_error |
| `voice_not_found` | 404 | invalid_request_error |
| `job_not_found` | 404 | invalid_request_error |
| `job_not_cancellable` | 409 | invalid_request_error |
| `job_not_ready` | 409 | invalid_request_error |
| `voice_limit` | 409 | invalid_request_error |
| `voice_name_taken` | 409 | invalid_request_error |
| `voice_display_name_invalid` | 400 | invalid_request_error |
| `voice_description_too_long` | 400 | invalid_request_error |
| `idempotency_key_reused` | 409 | invalid_request_error |
| `job_expired` | 410 | invalid_request_error |
| `request_too_large` | 413 | invalid_request_error |
| `sample_too_large` | 413 | invalid_request_error |
| `invalid_webhook_url` | 422 | invalid_request_error |
| `idempotency_key_invalid` | 422 | invalid_request_error |
| `consent_required` | 422 | invalid_request_error |
| `unsupported_audio` | 422 | invalid_request_error |
| `sample_too_long` | 422 | invalid_request_error |
| `rate_limited` | 429 | rate_limit_error |
| `internal_error` | 500 | api_error |
| `upstream_unavailable` | 503 | api_error |

Method không hỗ trợ trên một đường dẫn có tồn tại trả HTTP 405 với `code: invalid_request`.

## Nên xử lý thế nào

| Mã | Cách xử lý |
|---|---|
| `rate_limited` | Chờ `Retry-After` giây rồi thử lại. Xem [Giới hạn tốc độ](/docs-md/rate-limits.md). |
| `upstream_unavailable`, `internal_error` | Thử lại với backoff lũy thừa. Với `upstream_unavailable` của `POST /v1/audio/speech`, credit đã được hoàn. |
| `insufficient_credit` | Nạp thêm credit trong dashboard; không thử lại ngay. |
| `unauthorized` | Kiểm tra khóa API (có thể đã bị thu hồi). |
| Nhóm `invalid_request_error` | Sửa request; thử lại nguyên trạng sẽ lỗi tiếp. |

Lỗi trong phiên WebSocket là sự kiện `error` với cùng các `code`; xem [Voice agent qua WebSocket](/docs-md/realtime-websocket.md#errors).

