Hướng dẫn API

Lỗi

Xem dưới dạng Markdown Đã cập nhật 2026-10-22

Mọi điểm cuối đều lỗi theo cùng một cách: mã trạng thái HTTP và một phong bì JSON.

JSON

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}

Trường	Ý nghĩa
`type`	Phân loại rộng của lỗi. Dựa vào đây để quyết định cách xử lý.
`code`	Lý do chính xác, ổn định và máy có thể đọc. Mỗi mã có một phần bên dưới; `doc_url` liên kết đến phần đó.
`message`	Giải thích để con người đọc, an toàn để ghi nhật ký hoặc hiển thị cho nhà phát triển.
`param`	Tham số đầu vào hoặc header gây lỗi, nếu có.
`details`	Với lỗi đầu vào, mọi vấn đề được tìm thấy: `[{ "param", "message" }]`.
`request_id`	Yêu cầu liên quan, nếu có.

Không tính phí cho cuộc gọi trả về lỗi. Yêu cầu lỗi sau khi được chấp nhận vẫn có trạng thái failed, chứa error: { "type", "code", "message" } trong đối tượng yêu cầu và được hoàn tiền tự động.

Loại

Loại	Trạng thái HTTP	Cách xử lý
`invalid_request`	400, 413 hoặc 422	Sửa yêu cầu. Gửi lại cùng cuộc gọi sẽ tiếp tục lỗi.
`authentication_error`	401	Gửi khóa hợp lệ trong `Authorization: Bearer <key>`.
`permission_error`	403	Dùng khóa có scope cần thiết.
`not_found`	404	Kiểm tra id mô hình hoặc id yêu cầu.
`insufficient_credits`	402	Nạp tiền vào số dư API (`top_up_url` trong lỗi).
`budget_exceeded`	402	Ngân sách riêng của khóa đã dùng hết. Cuối cùng: yêu cầu chủ sở hữu khóa tăng ngân sách.
`conflict`	409	Tài nguyên không ở trạng thái cho phép cuộc gọi này.
`rate_limited`	429	Chờ `Retry-After` giây rồi thử lại.
`upstream_error`	502	Backend mô hình lỗi. Có thể thử lại với cùng `Idempotency-Key`: yêu cầu sẽ chạy lại; bạn không bị tính phí.
`service_unavailable`	503	API đang tạm dừng hoặc một phần phụ thuộc đang ngừng hoạt động. Thử lại sau.
`internal_error`	500	Lỗi phía chúng tôi. Thử lại; nếu vẫn tiếp diễn, liên hệ bộ phận hỗ trợ kèm thời gian và `request_id`.

Mã lỗi

`invalid_request`

Yêu cầu không đúng định dạng (400).

`invalid_json`

Phần thân không phải JSON hợp lệ (400).

`invalid_body`

Phần thân là JSON hợp lệ nhưng không phải đối tượng; đầu vào mô hình phải là một đối tượng JSON (400).

`body_too_large`

Phần thân lớn hơn 16 MB (413). Tải tệp lớn lên và truyền URL của chúng thay vào đó (xem Tệp).

`invalid_parameter`

Một tham số truy vấn có giá trị sai, chẳng hạn limit nằm ngoài 1 đến 100, wait không phải số, status hoặc category không xác định, hoặc storage khác permanent / temporary (400). param cho biết tham số đó.

`invalid_category`

GET /openapi.json?category= chỉ định một danh mục không tồn tại (400). GET https://api.doitong.com/v1/categories liệt kê các danh mục.

`invalid_cursor`

cursor của cuộc gọi danh sách không thuộc danh sách này (400). Bắt đầu lại mà không dùng cursor.

`invalid_idempotency_key`

Header Idempotency-Key trống hoặc dài hơn 255 ký tự (400).

`invalid_arguments`

Một cuộc gọi công cụ MCP thiếu đối số hoặc có đối số sai định dạng (chỉ MCP). param cho biết đối số đó.

`invalid_input`

Đầu vào mô hình không vượt qua kiểm tra xác thực (422): tham số không xác định (thông báo gợi ý tên hợp lệ gần nhất), tham số bắt buộc bị thiếu, sai kiểu, giá trị nằm ngoài danh sách hoặc phạm vi cho phép, hoặc đồng thời cung cấp tên chuẩn và tên gốc với các giá trị khác nhau. param là tham số lỗi đầu tiên và details liệt kê tất cả. Không tính phí.

`unsupported_file`

Một tệp có kiểu không được chấp nhận (422), chẳng hạn tệp tải lên có phần mở rộng không hỗ trợ hoặc content_type không khớp với phần mở rộng.

`invalid_webhook_url`

webhook_url không phải URL công khai https:// (422). Địa chỉ riêng tư, cục bộ và http:// thuần túy bị từ chối.

`missing_api_key`

Điểm cuối yêu cầu khóa API nhưng không nhận được khóa nào (401).

`invalid_api_key`

Khóa không xác định, đã bị thu hồi hoặc hết hạn (401).

`insufficient_scope`

Khóa thiếu scope mà cuộc gọi cần (403), chẳng hạn models:run để chạy hoặc models:read để đọc yêu cầu và số dư. Xem Xác thực.

`account_disabled`

Tài khoản đã đóng hoặc bị đình chỉ (403). Các khóa của tài khoản không còn hoạt động.

`not_found`

Đường dẫn không tồn tại (404).

`model_not_found`

Không có mô hình công khai nào có id này (404). Liệt kê mô hình bằng GET https://api.doitong.com/v1/models.

`request_not_found`

Không có yêu cầu nào có id này trong tài khoản của bạn (404). Yêu cầu của tài khoản khác không bao giờ hiển thị.

`insufficient_credits`

Số dư API của tài khoản (tín dụng API, 1.000 tín dụng API = 1 $ — không phải tín dụng của các ứng dụng Doitong) không đủ trả giá cuộc gọi này (402). Phản hồi được gửi trước khi tính phí. Lỗi chứa top_up_url; thêm tiền tại https://doitong.com/developers/dashboard#balance rồi thử lại.

JSON

{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
             "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }

`budget_exceeded`

Cuộc gọi sẽ vượt quá ngân sách riêng của khóa API tính bằng tín dụng API (402). Ngân sách do chủ sở hữu khóa đặt; thử lại không có tác dụng cho đến khi họ tăng ngân sách.

`conflict`

Cuộc gọi xung đột với trạng thái hiện tại của tài nguyên (409).

`idempotency_mismatch`

Idempotency-Key đã được dùng với phần thân khác (409). Dùng khóa mới cho thao tác mới.

`idempotency_in_progress`

Một yêu cầu có cùng Idempotency-Key đang được tạo (409). Chờ một lát rồi thử lại để nhận yêu cầu đó.

`request_active`

Yêu cầu vẫn đang queued hoặc running, nên chưa có tệp để xóa (409). Xóa chúng sau khi yêu cầu hoàn tất.

`not_cancelable`

Yêu cầu đã succeeded hoặc failed và không thể hủy (409).

`rate_limited`

Khóa đã tạo quá nhiều yêu cầu trong khoảng thời gian hiện tại (429). Xem các header X-RateLimit-* và Retry-After.

`too_many_inflight`

Tài khoản đã có 10 yêu cầu queued hoặc running (429). Bắt đầu yêu cầu tiếp theo khi một yêu cầu hoàn tất.

`upstream_error`

Backend mô hình từ chối hoặc làm lỗi yêu cầu (502 khi chạy, hoặc yêu cầu có trạng thái failed với mã này). Tín dụng API được hoàn tiền. Nếu chính backend từ chối đầu vào, cuộc gọi trả về 422 invalid_input cùng thông báo của backend.

`upstream_lost`

Backend mô hình không còn biết yêu cầu, nên sẽ không bao giờ có kết quả. Yêu cầu kết thúc ở trạng thái failed với mã này (kiểu upstream_error) và được hoàn tiền. Chạy lại yêu cầu.

`timeout`

Yêu cầu chạy lâu hơn giới hạn (15 phút cho hình ảnh, 60 cho video, 30 cho các loại khác) và bị dừng. Yêu cầu kết thúc ở trạng thái failed với mã này và được hoàn tiền.

`service_unavailable`

API tạm thời bị dừng hoặc một phần phụ thuộc như tải tệp đang ngừng hoạt động (503). Thử lại sau.

`internal_error`

Đã xảy ra lỗi phía chúng tôi (500). Thử lại; nếu vẫn tiếp diễn, liên hệ bộ phận hỗ trợ.

`charge_failed`

Không thể tính phí tài khoản do vấn đề nội bộ (500). Yêu cầu được đánh dấu failed; không khoản nào bị trừ. Thử lại.

`pricing_unavailable`

Giá của mô hình chưa được cấu hình, nên hiện không thể báo giá hoặc chạy mô hình (500).

Loại#

Mã lỗi#

invalid_request#

invalid_json#

invalid_body#

body_too_large#

invalid_parameter#

invalid_category#

invalid_cursor#

invalid_idempotency_key#

invalid_arguments#

invalid_input#

unsupported_file#

invalid_webhook_url#

missing_api_key#

invalid_api_key#

insufficient_scope#

account_disabled#

not_found#

model_not_found#

request_not_found#

insufficient_credits#

budget_exceeded#

conflict#

idempotency_mismatch#

idempotency_in_progress#

request_active#

not_cancelable#

rate_limited#

too_many_inflight#

upstream_error#

upstream_lost#

timeout#

service_unavailable#

internal_error#

charge_failed#

pricing_unavailable#