Tài liệu cho nhà phát triểnBắt đầu
Lỗi
Một cấu trúc lỗi duy nhất, mã lỗi ổn định, quy tắc thử lại rõ ràng.
Mọi phản hồi có mã ngoài 2xx đều có cùng một cấu trúc. Hãy xử lý lỗi dựa vào error.code, không bao giờ dựa vào message.
{
"error": {
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
"details": [
{
"path": "items[3].length",
"code": "out_of_range",
"message": "length must be greater than 0."
}
]
}
}| Trường | Nội dung |
|---|---|
code | Ổn định, dạng snake_case |
message | Tiếng Anh, dùng cho log |
request_id | Cũng có trong X-Request-Id. Cung cấp mã này khi liên hệ hỗ trợ |
details[] | Với 400/422: path, code, message cho từng lỗi |
Mã lỗi
| Trạng thái | Mã | Ý nghĩa | Cách xử lý | Thử lại |
|---|---|---|---|---|
| 400 | invalid_json | Nội dung không phải JSON hợp lệ hoặc có trường sai kiểu. | Sửa nội dung yêu cầu. | Không |
| 401 | unauthorized | Thiếu khóa API, khóa sai định dạng hoặc không xác định. | Gửi header Authorization: Bearer cd_live_…; kiểm tra xem khóa đã được sao chép đầy đủ chưa. | Không |
| 401 | key_revoked | Khóa đã bị thu hồi. | Tạo khóa mới trong console dành cho nhà phát triển. | Không |
| 401 | key_expired | Khóa đã quá ngày hết hạn. | Tạo khóa mới trong console dành cho nhà phát triển. | Không |
| 402 | insufficient_credits | Credit khả dụng không đủ cho lần chạy rẻ nhất có thể của tác vụ này. | Mua gói credit hoặc chờ credit hằng tháng; bạn chưa bị trừ credit nào. | Không |
| 403 | ip_not_allowed | IP gọi đến không nằm trong danh sách IP được phép của khóa. | Gọi từ một IP được phép hoặc sửa danh sách IP được phép. | Không |
| 403 | subscription_inactive | Tổ chức không có gói đăng ký đang hoạt động nào bao gồm API. | Gia hạn gói đăng ký. | Không |
| 403 | account_inactive | Tổ chức bị tạm ngưng, hoặc không có chủ sở hữu nào có tài khoản đang hoạt động. | Liên hệ bộ phận hỗ trợ. | Không |
| 403 | scope_missing | Khóa thiếu phạm vi quyền mà endpoint này yêu cầu. | Dùng khóa có phạm vi quyền cần thiết (pack:write, jobs:read, account:read, resources:read, resources:write). | Không |
| 403 | preset_read_only | Không thể thay đổi hoặc xóa xe thiết lập sẵn. | Tạo xe riêng bằng POST /v1/vehicles. | Không |
| 403 | plan_limit_reached | Gói của tổ chức không cho phép thêm dự án hoặc kiện hàng. | Xóa các dự án không còn cần, hoặc chuyển sang gói lớn hơn. | Không |
| 404 | not_found | Không có endpoint /v1 nào khớp với phương thức và đường dẫn này. | Đối chiếu phương thức và đường dẫn với danh sách endpoint. | Không |
| 404 | job_not_found | Tổ chức của bạn không có tác vụ nào với ID này. | Kiểm tra lại ID. | Không |
| 404 | vehicle_not_found | Không có xe nào với ID này trong số xe thiết lập sẵn hoặc xe của tổ chức. | Đối chiếu ID với GET /v1/vehicles. | Không |
| 404 | template_not_found | Tổ chức của bạn không có mẫu hàng nào với ID này. | Đối chiếu ID với GET /v1/templates. | Không |
| 404 | project_not_found | Tổ chức của bạn không có dự án nào với ID này. | Đối chiếu ID với GET /v1/projects. | Không |
| 409 | job_not_finished | Tác vụ vẫn đang chờ hoặc đang chạy. | Gọi GET /v1/jobs/{id} định kỳ cho đến khi status là succeeded. | Có |
| 409 | project_busy | Dự án đang được xếp hàng (trong ứng dụng hoặc bởi một tác vụ khác). | Chờ lượt chạy đó kết thúc rồi thử lại. | Có |
| 409 | job_failed | Tác vụ thất bại; không có kết quả. | Đọc job.error; lỗi từ phía chúng tôi không bị tính phí (time_limit_exceeded được tính phí như tác vụ bị hủy) — gửi lại nếu nguyên nhân chỉ là tạm thời. | Không |
| 409 | job_canceled | Tác vụ đã bị hủy; không có kết quả. | Gửi lại nếu cần. | Không |
| 409 | job_already_finished | Tác vụ đã kết thúc và không thể hủy. | Không cần làm gì. | Không |
| 400 | idempotency_key_invalid | Header Idempotency-Key dài hơn 128 ký tự. | Dùng khóa ngắn hơn (UUID là đủ). | Không |
| 410 | result_expired | Kết quả đã quá thời gian lưu trữ và đã bị xóa. | Gửi lại tác vụ nếu bạn cần sơ đồ lần nữa. | Không |
| 413 | payload_too_large | Nội dung yêu cầu vượt quá 10 MB. | Gửi ít kiện hàng hơn hoặc đơn giản hóa chúng. | Không |
| 422 | validation_failed | Yêu cầu là JSON đúng cú pháp nhưng mô tả một tác vụ không hợp lệ. details[] liệt kê mọi lỗi. | Sửa từng trường được chỉ ra trong details[].path; lỗi kiểm tra hợp lệ không bị tính phí. | Không |
| 429 | rate_limited | Quá nhiều yêu cầu trong phút, giờ hoặc ngày hiện tại (theo khóa hoặc theo tổ chức), hoặc có hơn 60 lần xác thực thất bại mỗi phút từ địa chỉ IP của bạn. | Chờ số giây trong Retry-After, rồi thử lại với backoff. | Có |
| 429 | too_many_jobs | Tổ chức đã đạt số tác vụ tối đa đang chờ + đang chạy. | Chờ các tác vụ đang chạy hoàn tất rồi thử lại. | Có |
| 500 | internal_error | Đã xảy ra lỗi ở phía chúng tôi. | Thử lại với backoff; nếu lỗi vẫn tiếp diễn, hãy cung cấp request_id. | Có |
| 503 | api_disabled | API tạm thời bị tắt (bảo trì) hoặc đã bị tắt cho tổ chức. | Thử lại sau. | Có |
Chi tiết lỗi kiểm tra hợp lệ
details[].code khi gặp 422 validation_failed:
| Mã | Ý nghĩa |
|---|---|
required | Thiếu một trường bắt buộc |
invalid_value | Sai kiểu hoặc không thuộc các giá trị cho phép |
out_of_range | Quá nhỏ, quá lớn hoặc quá dài |
duplicate_id | Một ID bị dùng hai lần |
unknown_vehicle | Không có xe thiết lập sẵn hay xe nào của bạn với vehicle_id này |
unknown_template | Không có mẫu hàng nào của bạn với template_id này |
type_not_allowed | Loại xe chưa được bật cho tổ chức của bạn |
unknown_group | Kiện hàng tham chiếu một nhóm không có trong danh sách |
does_not_fit | Kiện hàng không vừa với xe nào đã khai báo |
too_many_items | Số kiện vượt giới hạn của tác vụ |
too_many_vehicles | Số xe vượt giới hạn của tác vụ |
unknown_field | Trường mà API không nhận biết |
Lỗi của tác vụ
Tác vụ failed hoặc canceled cho biết lý do trong job.error.code:
| Mã | Ý nghĩa |
|---|---|
canceled | Bị hủy bằng DELETE /v1/jobs/{id}. Tính phí cơ bản + phần tính toán đã dùng. |
time_limit_exceeded | Hết thời gian tính toán trước khi xếp xong bất kỳ xe nào. Tính phí như tác vụ bị hủy: phí tác vụ, phụ phí tải lớn và phần tính toán đã dùng, không bao giờ tính phí theo xe. |
engine_failed | Thuật toán xếp hàng gặp lỗi. Không tính phí. |
queue_timeout | Tác vụ chờ tài nguyên tính toán quá lâu. Không tính phí. |
server_restarted | Dịch vụ khởi động lại khi tác vụ đang chờ hoặc đang chạy. Không tính phí. |
Thử lại
Thử lại khi gặp 429, 500 và 503 theo cơ chế exponential backoff, tuân theo Retry-After. Gửi cùng Idempotency-Key (Idempotency). Với các mã 4xx khác, không bao giờ gửi lại yêu cầu y nguyên.