# Lỗi

> **Tóm tắt** — Rẽ nhánh theo `error.code`, không theo thông điệp. Chỉ thử lại các mã ghi Có, và lỗi mạng, với cùng `Idempotency-Key`. Mỗi lỗi có link tới đúng mục của nó trên trang này.

Lỗi là JSON: `{"error": {"code": "...", "message": "..."}}`. Rẽ nhánh theo `code`; thông điệp dành cho người đọc và có thể đổi. Mọi phản hồi có header `X-Request-Id`: gửi nó khi liên hệ hỗ trợ.

Chỉ thử lại các mã ghi **Có** dưới đây và lỗi mạng, với cùng `Idempotency-Key`. Chờ `Retry-After` nếu phản hồi có, không thì lùi dần kèm jitter. Đừng thử lại các mã khác: cùng request sẽ lỗi y như cũ.

## Thân lỗi và header
**Đang triển khai.** Mọi câu trả lời lỗi của `/v2`, ở cả hai dạng (run và [Jobs API](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-errors)), có thêm các mục sau, ngoài mọi field đã có:

| Ở đâu | Tên | Nói gì |
|---|---|---|
| Body | `error.docs_url` | Link tới mục của mã này trên trang này, ví dụ `https://docs.wandura.ai/developers/api-v2/errors#product-busy`. Mã chưa có mục riêng thì link tới trang này. |
| Body | `error.retryable` | `true` khi gửi lại y nguyên request sau đó có thể thành công: mọi `429` và `5xx` (ví dụ `product_busy`, `service_unavailable`). `false` với lỗi đầu vào và lỗi khoá. Lỗi Jobs API vốn đã có field này. |
| Header | `Wandura-Error-Code` | Cùng giá trị với `error.code`. |
| Header | `Wandura-Should-Retry` | `true` hoặc `false`, cùng giá trị với `error.retryable`. |

`Retry-After` và `X-Request-Id` giữ nguyên. Cả bốn mục đều không bắt buộc: không dùng thì bỏ qua, và thiếu `retryable` thì làm theo bảng dưới.

```http
HTTP/1.1 429
Retry-After: 5
Wandura-Error-Code: product_busy
Wandura-Should-Retry: true

{"error":{"code":"product_busy","message":"…","limit":20,"retry_after_s":5,"retryable":true,"docs_url":"https://docs.wandura.ai/developers/api-v2/errors#product-busy"}}
```

## Lỗi của run
| HTTP | `code` | Thử lại? |
|---|---|---|
| 400 | [`invalid_request`](https://docs.wandura.ai/vi/developers/api-v2/errors#invalid-request) | Không |
| 400 | [`idempotency_key_required`](https://docs.wandura.ai/vi/developers/api-v2/errors#idempotency-key-required) | Không |
| 400 | [`end_user_id_required`](https://docs.wandura.ai/vi/developers/api-v2/errors#end-user-id-required) | Không |
| 401 | [`invalid_api_key`](https://docs.wandura.ai/vi/developers/api-v2/errors#invalid-api-key) | Không |
| 401 | [`api_key_expired`](https://docs.wandura.ai/vi/developers/api-v2/errors#api-key-expired) | Không |
| 402 | [`wallet_empty`](https://docs.wandura.ai/vi/developers/api-v2/errors#wallet-empty) | Không |
| 403 | [`insufficient_scope`](https://docs.wandura.ai/vi/developers/api-v2/errors#insufficient-scope) | Không |
| 403 | [`style_not_allowed`](https://docs.wandura.ai/vi/developers/api-v2/errors#style-not-allowed) | Không |
| 404 | [`style_not_found`](https://docs.wandura.ai/vi/developers/api-v2/errors#style-not-found) | Không |
| 404 | [`run_not_found`](https://docs.wandura.ai/vi/developers/api-v2/errors#run-not-found) | Không |
| 404 | [`not_found`](https://docs.wandura.ai/vi/developers/api-v2/errors#not-found) | Không |
| 409 | [`idempotency_key_reused`](https://docs.wandura.ai/vi/developers/api-v2/errors#idempotency-key-reused) | Không |
| 409 | [`run_not_cancelable`](https://docs.wandura.ai/vi/developers/api-v2/errors#run-not-cancelable) | Không |
| 413 | [`file_too_large`](https://docs.wandura.ai/vi/developers/api-v2/errors#file-too-large) | Không |
| 415 | [`unsupported_content_type`](https://docs.wandura.ai/vi/developers/api-v2/errors#unsupported-content-type) | Không |
| 429 | [`end_user_cap_reached`](https://docs.wandura.ai/vi/developers/api-v2/errors#end-user-cap-reached) | Có |
| 429 | [`gateway_rate_limited`](https://docs.wandura.ai/vi/developers/api-v2/errors#gateway-rate-limited) | Có |
| 429 | [`uploads_rate_limited`](https://docs.wandura.ai/vi/developers/api-v2/errors#uploads-rate-limited) | Có |
| 429 | [`product_busy`](https://docs.wandura.ai/vi/developers/api-v2/errors#product-busy) | Có |
| 500 | [`internal_error`](https://docs.wandura.ai/vi/developers/api-v2/errors#internal-error) | Có |
| 503 | [`style_unavailable`](https://docs.wandura.ai/vi/developers/api-v2/errors#style-unavailable) | Có |
| 503 | [`uploads_unavailable`](https://docs.wandura.ai/vi/developers/api-v2/errors#uploads-unavailable) | Có |
| 503 | [`service_unavailable`](https://docs.wandura.ai/vi/developers/api-v2/errors#service-unavailable) | Có |

Câu trả lời submit, kể cả `429`, có `X-Concurrency-Limit`, `X-Concurrency-Running` và `X-Concurrency-Waiting`. Mỗi câu trả lời `product_busy` và `gateway_rate_limited` là một lần bị từ chối: nó được liệt kê ở `GET /v2/queue/refusals`. Xem [Hàng chờ và nghẽn](https://docs.wandura.ai/vi/developers/api-v2/queue-and-congestion).

Run lỗi sau khi đã được nhận không phải lỗi HTTP: run kết thúc `failed` hoặc `nsfw` kèm [lý do miễn phí](https://docs.wandura.ai/vi/developers/api-v2/concepts#free-runs), và bạn không bị tính tiền.

#### `invalid_request`
`400`, không thử lại. The body or a parameter is wrong; the message says which.

#### `idempotency_key_required`
`400`, không thử lại. Send an `Idempotency-Key` header (max 255 chars) on every submit.

#### `end_user_id_required`
`400`, không thử lại. `end_user_id` is required: the id of the person in your app this run is for.

#### `invalid_api_key`
`401`, không thử lại. Missing, unknown or revoked API key.

#### `api_key_expired`
`401`, không thử lại. This API key has expired. Create or rotate a key.

#### `wallet_empty`
`402`, không thử lại. The product wallet and the org pool cannot cover this run. Add money, then retry.

#### `insufficient_scope`
`403`, không thử lại. **Đang triển khai.** Key này có quyền Read only (chỉ đọc): đọc được run và style, không gửi, huỷ, chia sẻ hay tải tệp lên được. Dùng key có quyền Run styles. 
#### `style_not_allowed`
`403`, không thử lại. **Đang triển khai.** Key này chỉ được chạy một số style, và style này không nằm trong đó. Dùng key có style này, hoặc nhờ admin của org.

Chỉ key tạo kèm quyền hoặc danh sách style được phép mới nhận `403` (xem [Khoá API](https://docs.wandura.ai/vi/developers/api-v2/concepts#api-keys)). Key tạo không kèm hai thứ đó không bao giờ nhận.

#### `style_not_found`
`404`, không thử lại. No style with that id for your org (or not public).

#### `run_not_found`
`404`, không thử lại. No run with that id for this product.

#### `not_found`
`404`, không thử lại. No such endpoint.

#### `idempotency_key_reused`
`409`, không thử lại. This `Idempotency-Key` was already used with a different body. Use a new key for a new run.

#### `run_not_cancelable`
`409`, không thử lại. Only queued runs can be canceled.

#### `file_too_large`
`413`, không thử lại. The file is over the size limit for its type.

#### `unsupported_content_type`
`415`, không thử lại. Uploads accept JPEG, PNG, WEBP, MP4, MOV and WEBM.

#### `end_user_cap_reached`
`429`, thử lại. This end user reached the daily run cap. Retry after the `Retry-After` header (resets 00:00 UTC).

#### `gateway_rate_limited`
`429`, thử lại. A gateway key's product reached its runs-per-minute limit. Retry after the `Retry-After` header.

#### `uploads_rate_limited`
`429`, thử lại. Your org reached its presigned uploads per minute. Retry after the `Retry-After` header.

#### `product_busy`
`429`, thử lại. Your product's concurrency slots and its queue are full. Retry after the `Retry-After` header (about 5 s).

#### `internal_error`
`500`, thử lại. Something went wrong on our side. Retry with the same `Idempotency-Key`; quote `X-Request-Id` to support.

#### `style_unavailable`
`503`, thử lại. This style cannot run on a live key right now (no model behind it). Test keys still return a sample.

#### `uploads_unavailable`
`503`, thử lại. Uploads are not available on this deployment right now.

#### `service_unavailable`
`503`, thử lại. The job queue is briefly unavailable; nothing was created or charged. Retry with the same `Idempotency-Key` after the `Retry-After` header.

## Lỗi của Jobs API
[Jobs API](https://docs.wandura.ai/vi/developers/api-v2/jobs#errors) (`/v2/jobs`, `/v2/models`, `GET /v2/styles`) trả `{"error": {"code", "message", "retryable"}}`, thêm `details` với `INVALID_INPUT`, bằng mã riêng:

| HTTP | `code` | `retryable` |
|---|---|---|
| 422 | [`INVALID_INPUT`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-invalid-input) | false |
| 401 | [`UNAUTHORIZED`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-unauthorized) | false |
| 402 | [`INSUFFICIENT_CREDITS`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-insufficient-credits) | false |
| 403 | [`FORBIDDEN`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-forbidden) | false |
| 404 | [`NOT_FOUND`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-not-found) | false |
| 409 | [`IDEMPOTENCY_KEY_REUSED`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-idempotency-key-reused) | false |
| 409 | [`JOB_NOT_CANCELLABLE`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-job-not-cancellable) | false |
| 429 | [`RATE_LIMITED`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-rate-limited) | true |
| 429 | [`PRODUCT_BUSY`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-product-busy) | true |
| 429 | [`END_USER_LIMIT_REACHED`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-end-user-limit-reached) | true |
| 500 | [`INTERNAL_ERROR`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-internal-error) | true |
| 503 | [`SERVICE_UNAVAILABLE`](https://docs.wandura.ai/vi/developers/api-v2/errors#jobs-service-unavailable) | true |

#### `INVALID_INPUT`
`422`, không thử lại. The body or a header is wrong; `details[]` lists each `{field, reason}`. Các endpoint run (`POST /v2/runs`, `POST /v2/styles/{style}`) trả cùng mã này với `400` khi `resolution` hoặc số file không hợp style.

#### `UNAUTHORIZED`
`401`, không thử lại. Missing, unknown, revoked or expired API key.

#### `INSUFFICIENT_CREDITS`
`402`, không thử lại. The product's wallet cannot cover the job. Add funds, then retry.

#### `FORBIDDEN`
`403`, không thử lại. Key hợp lệ nhưng không được làm việc này. Đang triển khai: key quyền Read only gửi hoặc huỷ job, hoặc key chỉ được chạy style khác (xem [Khoá API](https://docs.wandura.ai/vi/developers/api-v2/concepts#api-keys)). Trước đó: chưa trả. 
#### `NOT_FOUND`
`404`, không thử lại. No such job, model or endpoint for this key.

#### `IDEMPOTENCY_KEY_REUSED`
`409`, không thử lại. This `Idempotency-Key` was already used with a different body. Use a new key for a new job.

#### `JOB_NOT_CANCELLABLE`
`409`, không thử lại. Only queued jobs can be cancelled.

#### `RATE_LIMITED`
`429`, thử lại. Too many jobs submitted this minute for this product. Retry after the `Retry-After` header.

#### `PRODUCT_BUSY`
`429`, thử lại. Your product's concurrency slots and its queue are full. Retry after the `Retry-After` header (about 5 s).

#### `END_USER_LIMIT_REACHED`
`429`, thử lại. This end user reached the daily job cap. Retry after the `Retry-After` header (resets 00:00 UTC).

#### `INTERNAL_ERROR`
`500`, thử lại. Something went wrong on Wandura's side. Retry with the same `Idempotency-Key`.

#### `SERVICE_UNAVAILABLE`
`503`, thử lại. This style cannot run on a live key right now (test keys still return a sample). Or the job queue is briefly unavailable: nothing was created or charged; retry after `Retry-After` with the same `Idempotency-Key`.

Job kết thúc không có kết quả (`failed`, `timeout`) không phải lỗi HTTP: `error.code` của nó nằm ở mục [Trạng thái](https://docs.wandura.ai/vi/developers/api-v2/jobs#statuses) trên trang Jobs API.