Lịch sử thay đổi
Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
- 19/10/2026 · +2 −2 dòng
Xem thay đổi
⋯ #### `daily_cap_reached` {#daily-cap-reached} - `429`, không thử lại. **Đang triển khai.** Product của bạn đã chạm trần chi tiêu trong ngày: tiền đã trừ của các run live cộng tiền đang giữ, tính theo ngày giờ Việt Nam (đặt lại lúc 00:00 UTC+7). Không có gì được tạo hay bị trừ tiền. Body có `cap_usd` là mức trần tính bằng USD, và không có `Retry-After`. Chờ sang ngày mới, hoặc nhờ admin của org nâng trần. + `429`, không thử lại. Product của bạn đã chạm trần chi tiêu trong ngày: tiền đã trừ của các run live cộng tiền đang giữ, tính theo ngày giờ Việt Nam (đặt lại lúc 00:00 UTC+7). Không có gì được tạo hay bị trừ tiền. Body có `cap_usd` là mức trần tính bằng USD, và không có `Retry-After`. Chờ sang ngày mới, hoặc nhờ admin của org nâng trần. #### `gateway_rate_limited` {#gateway-rate-limited} ⋯ #### `DAILY_CAP_REACHED` {#jobs-daily-cap-reached} - `429`, không thử lại. **Đang triển khai.** Product này đã chạm trần chi tiêu trong ngày (ngày đặt lại lúc 00:00 giờ Việt Nam, UTC+7). Không có gì được tạo hay bị giữ tiền. Chờ sang ngày mới, hoặc nhờ admin của org nâng trần. Xem [Wandura C1.1](wandura-c1-1.md#errors). + `429`, không thử lại. Product này đã chạm trần chi tiêu trong ngày (ngày đặt lại lúc 00:00 giờ Việt Nam, UTC+7). Không có gì được tạo hay bị giữ tiền. Chờ sang ngày mới, hoặc nhờ admin của org nâng trần. Xem [Wandura C1.1](wandura-c1-1.md#errors). #### `INTERNAL_ERROR` {#jobs-internal-error} ⋯
- 19/10/2026 · +8 −0 dòng
Xem thay đổi
⋯ | 415 | [`unsupported_content_type`](#unsupported-content-type) | Không | | 429 | [`end_user_cap_reached`](#end-user-cap-reached) | Có | + | 429 | [`daily_cap_reached`](#daily-cap-reached) | Không | | 429 | [`gateway_rate_limited`](#gateway-rate-limited) | Có | | 429 | [`uploads_rate_limited`](#uploads-rate-limited) | Có | ⋯ `429`, thử lại. This end user reached the daily run cap. Retry after the `Retry-After` header (resets 00:00 UTC). + #### `daily_cap_reached` {#daily-cap-reached} + `429`, không thử lại. **Đang triển khai.** Product của bạn đã chạm trần chi tiêu trong ngày: tiền đã trừ của các run live cộng tiền đang giữ, tính theo ngày giờ Việt Nam (đặt lại lúc 00:00 UTC+7). Không có gì được tạo hay bị trừ tiền. Body có `cap_usd` là mức trần tính bằng USD, và không có `Retry-After`. Chờ sang ngày mới, hoặc nhờ admin của org nâng trần. + #### `gateway_rate_limited` {#gateway-rate-limited} `429`, thử lại. A gateway key's product reached its runs-per-minute limit. Retry after the `Retry-After` header. ⋯ | 429 | [`PRODUCT_BUSY`](#jobs-product-busy) | true | | 429 | [`END_USER_LIMIT_REACHED`](#jobs-end-user-limit-reached) | true | + | 429 | [`DAILY_CAP_REACHED`](#jobs-daily-cap-reached) | false | | 500 | [`INTERNAL_ERROR`](#jobs-internal-error) | true | | 503 | [`SERVICE_UNAVAILABLE`](#jobs-service-unavailable) | true | ⋯ `429`, thử lại. This end user reached the daily job cap. Retry after the `Retry-After` header (resets 00:00 UTC). + #### `DAILY_CAP_REACHED` {#jobs-daily-cap-reached} + `429`, không thử lại. **Đang triển khai.** Product này đã chạm trần chi tiêu trong ngày (ngày đặt lại lúc 00:00 giờ Việt Nam, UTC+7). Không có gì được tạo hay bị giữ tiền. Chờ sang ngày mới, hoặc nhờ admin của org nâng trần. Xem [Wandura C1.1](wandura-c1-1.md#errors). + #### `INTERNAL_ERROR` {#jobs-internal-error} `500`, thử lại. Something went wrong on Wandura's side. Retry with the same `Idempotency-Key`. ⋯
- 16/10/2026 · +173 −27 dòng
Xem thay đổi
# 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`. + > **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ũ. - | HTTP | `code` | Thử lại? | Việc cần làm | - |---|---|---|---| - | 400 | `invalid_request` | Không | The body or a parameter is wrong; the message says which. | - | 400 | `idempotency_key_required` | Không | Send an Idempotency-Key header (max 255 chars) on every submit. | - | 400 | `end_user_id_required` | Không | end_user_id is required: the id of the person in your app this run is for. | - | 401 | `invalid_api_key` | Không | Missing, unknown or revoked API key. | - | 401 | `api_key_expired` | Không | This API key has expired. Create or rotate a key. | - | 402 | `wallet_empty` | Không | The product wallet and the org pool cannot cover this run. Add money, then retry. | - | 403 | `insufficient_scope` | Không | Đ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. | - | 403 | `style_not_allowed` | Không | Đ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. | - | 404 | `style_not_found` | Không | No style with that id for your org (or not public). | - | 404 | `run_not_found` | Không | No run with that id for this product. | - | 404 | `not_found` | Không | No such endpoint. | - | 409 | `idempotency_key_reused` | Không | This Idempotency-Key was already used with a different body. Use a new key for a new run. | - | 409 | `run_not_cancelable` | Không | Only queued runs can be canceled. | - | 413 | `file_too_large` | Không | The file is over the size limit for its type. | - | 415 | `unsupported_content_type` | Không | Uploads accept JPEG, PNG, WEBP, MP4, MOV and WEBM. | - | 429 | `end_user_cap_reached` | Có | This end user reached the daily run cap. Retry after the Retry-After header (resets 00:00 UTC). | - | 429 | `gateway_rate_limited` | Có | A gateway key's product reached its runs-per-minute limit. Retry after the Retry-After header. | - | 429 | `uploads_rate_limited` | Có | Your org reached its presigned uploads per minute. Retry after the Retry-After header. | - | 429 | `product_busy` | Có | Your product's concurrency slots and its queue are full. Retry after the Retry-After header (about 5 s). | - | 500 | `internal_error` | Có | Something went wrong on our side. Retry with the same Idempotency-Key; quote X-Request-Id to support. | - | 503 | `style_unavailable` | Có | This style cannot run on a live key right now (no model behind it). Test keys still return a sample. | - | 503 | `uploads_unavailable` | Có | Uploads are not available on this deployment right now. | - | 503 | `service_unavailable` | Có | The job queue is briefly unavailable; nothing was created or charged. Retry with the same Idempotency-Key after the Retry-After header. | + ## Thân lỗi và header {#error-body} + **Đang triển khai.** Mọi câu trả lời lỗi của `/v2`, ở cả hai dạng (run và [Jobs API](#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 {#run-errors} + + | HTTP | `code` | Thử lại? | + |---|---|---| + | 400 | [`invalid_request`](#invalid-request) | Không | + | 400 | [`idempotency_key_required`](#idempotency-key-required) | Không | + | 400 | [`end_user_id_required`](#end-user-id-required) | Không | + | 401 | [`invalid_api_key`](#invalid-api-key) | Không | + | 401 | [`api_key_expired`](#api-key-expired) | Không | + | 402 | [`wallet_empty`](#wallet-empty) | Không | + | 403 | [`insufficient_scope`](#insufficient-scope) | Không | + | 403 | [`style_not_allowed`](#style-not-allowed) | Không | + | 404 | [`style_not_found`](#style-not-found) | Không | + | 404 | [`run_not_found`](#run-not-found) | Không | + | 404 | [`not_found`](#not-found) | Không | + | 409 | [`idempotency_key_reused`](#idempotency-key-reused) | Không | + | 409 | [`run_not_cancelable`](#run-not-cancelable) | Không | + | 413 | [`file_too_large`](#file-too-large) | Không | + | 415 | [`unsupported_content_type`](#unsupported-content-type) | Không | + | 429 | [`end_user_cap_reached`](#end-user-cap-reached) | Có | + | 429 | [`gateway_rate_limited`](#gateway-rate-limited) | Có | + | 429 | [`uploads_rate_limited`](#uploads-rate-limited) | Có | + | 429 | [`product_busy`](#product-busy) | Có | + | 500 | [`internal_error`](#internal-error) | Có | + | 503 | [`style_unavailable`](#style-unavailable) | Có | + | 503 | [`uploads_unavailable`](#uploads-unavailable) | Có | + | 503 | [`service_unavailable`](#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](queue-and-congestion.md). 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í](concepts.md#free-runs), và bạn không bị tính tiền. + #### `invalid_request` {#invalid-request} + `400`, không thử lại. The body or a parameter is wrong; the message says which. + + #### `idempotency_key_required` {#idempotency-key-required} + `400`, không thử lại. Send an `Idempotency-Key` header (max 255 chars) on every submit. + + #### `end_user_id_required` {#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` {#invalid-api-key} + `401`, không thử lại. Missing, unknown or revoked API key. + + #### `api_key_expired` {#api-key-expired} + `401`, không thử lại. This API key has expired. Create or rotate a key. + + #### `wallet_empty` {#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` {#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` {#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](concepts.md#api-keys)). Key tạo không kèm hai thứ đó không bao giờ nhận. - [Jobs API](jobs.md#errors) dùng mã lỗi riêng. + #### `style_not_found` {#style-not-found} + `404`, không thử lại. No style with that id for your org (or not public). + + #### `run_not_found` {#run-not-found} + `404`, không thử lại. No run with that id for this product. + + #### `not_found` {#not-found} + `404`, không thử lại. No such endpoint. + + #### `idempotency_key_reused` {#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` {#run-not-cancelable} + `409`, không thử lại. Only queued runs can be canceled. + + #### `file_too_large` {#file-too-large} + `413`, không thử lại. The file is over the size limit for its type. + + #### `unsupported_content_type` {#unsupported-content-type} + `415`, không thử lại. Uploads accept JPEG, PNG, WEBP, MP4, MOV and WEBM. + + #### `end_user_cap_reached` {#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` {#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` {#uploads-rate-limited} + `429`, thử lại. Your org reached its presigned uploads per minute. Retry after the `Retry-After` header. + + #### `product_busy` {#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` {#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` {#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` {#uploads-unavailable} + `503`, thử lại. Uploads are not available on this deployment right now. + + #### `service_unavailable` {#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-errors} + + [Jobs API](jobs.md#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`](#jobs-invalid-input) | false | + | 401 | [`UNAUTHORIZED`](#jobs-unauthorized) | false | + | 402 | [`INSUFFICIENT_CREDITS`](#jobs-insufficient-credits) | false | + | 403 | [`FORBIDDEN`](#jobs-forbidden) | false | + | 404 | [`NOT_FOUND`](#jobs-not-found) | false | + | 409 | [`IDEMPOTENCY_KEY_REUSED`](#jobs-idempotency-key-reused) | false | + | 409 | [`JOB_NOT_CANCELLABLE`](#jobs-job-not-cancellable) | false | + | 429 | [`RATE_LIMITED`](#jobs-rate-limited) | true | + | 429 | [`PRODUCT_BUSY`](#jobs-product-busy) | true | + | 429 | [`END_USER_LIMIT_REACHED`](#jobs-end-user-limit-reached) | true | + | 500 | [`INTERNAL_ERROR`](#jobs-internal-error) | true | + | 503 | [`SERVICE_UNAVAILABLE`](#jobs-service-unavailable) | true | + + #### `INVALID_INPUT` {#jobs-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` {#jobs-unauthorized} + `401`, không thử lại. Missing, unknown, revoked or expired API key. + + #### `INSUFFICIENT_CREDITS` {#jobs-insufficient-credits} + `402`, không thử lại. The product's wallet cannot cover the job. Add funds, then retry. + + #### `FORBIDDEN` {#jobs-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](concepts.md#api-keys)). Trước đó: chưa trả. + #### `NOT_FOUND` {#jobs-not-found} + `404`, không thử lại. No such job, model or endpoint for this key. + + #### `IDEMPOTENCY_KEY_REUSED` {#jobs-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` {#jobs-job-not-cancellable} + `409`, không thử lại. Only queued jobs can be cancelled. + + #### `RATE_LIMITED` {#jobs-rate-limited} + `429`, thử lại. Too many jobs submitted this minute for this product. Retry after the `Retry-After` header. + + #### `PRODUCT_BUSY` {#jobs-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` {#jobs-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` {#jobs-internal-error} + `500`, thử lại. Something went wrong on Wandura's side. Retry with the same `Idempotency-Key`. + + #### `SERVICE_UNAVAILABLE` {#jobs-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](jobs.md#statuses) trên trang Jobs API.
- 16/10/2026 · +4 −0 dòng
Xem thay đổi
⋯ | 401 | `api_key_expired` | Không | This API key has expired. Create or rotate a key. | | 402 | `wallet_empty` | Không | The product wallet and the org pool cannot cover this run. Add money, then retry. | + | 403 | `insufficient_scope` | Không | Đ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. | + | 403 | `style_not_allowed` | Không | Đ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. | | 404 | `style_not_found` | Không | No style with that id for your org (or not public). | | 404 | `run_not_found` | Không | No run with that id for this product. | ⋯ 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í](concepts.md#free-runs), và bạn không bị tính tiền. + 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](concepts.md#api-keys)). Key tạo không kèm hai thứ đó không bao giờ nhận. + [Jobs API](jobs.md#errors) dùng mã lỗi riêng.
- 15/10/2026 · +5 −0 dòng
Xem thay đổi
⋯ | 429 | `end_user_cap_reached` | Có | This end user reached the daily run cap. Retry after the Retry-After header (resets 00:00 UTC). | | 429 | `gateway_rate_limited` | Có | A gateway key's product reached its runs-per-minute limit. Retry after the Retry-After header. | + | 429 | `uploads_rate_limited` | Có | Your org reached its presigned uploads per minute. Retry after the Retry-After header. | + | 429 | `product_busy` | Có | Your product's concurrency slots and its queue are full. Retry after the Retry-After header (about 5 s). | | 500 | `internal_error` | Có | Something went wrong on our side. Retry with the same Idempotency-Key; quote X-Request-Id to support. | | 503 | `style_unavailable` | Có | This style cannot run on a live key right now (no model behind it). Test keys still return a sample. | | 503 | `uploads_unavailable` | Có | Uploads are not available on this deployment right now. | + | 503 | `service_unavailable` | Có | The job queue is briefly unavailable; nothing was created or charged. Retry with the same Idempotency-Key after the Retry-After header. | + 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](queue-and-congestion.md). + 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í](concepts.md#free-runs), và bạn không bị tính tiền. ⋯
- 14/10/2026 · Tạo trang