Lỗi thường gặp

Định dạng phản hồi lỗi

Các endpoint mô hình trả lỗi dưới dạng JSON:

{
  "error": {
    "message": "Insufficient user quota, remaining: ＄0.000000 (request id: 202610230158421013999388268d9d615)",
    "type": "error",
    "code": "insufficient_user_quota"
  }
}

message là mô tả dễ đọc, kết thúc bằng (request id: <id>). Cùng id đó cũng có trong header X-Oneapi-Request-Id; hãy gửi kèm khi liên hệ hỗ trợ.
code là mã lỗi máy đọc được. Một số lỗi để chuỗi rỗng; khi đó hãy dựa vào mã trạng thái HTTP.
message được bản địa hóa theo ngôn ngữ tài khoản hoặc Accept-Language và có thể thay đổi, nên logic chương trình hãy dựa vào mã trạng thái HTTP và code.

Claude Messages (/v1/messages) trả về {"type": "error", "error": {"type": "...", "message": "..."}} thay vào đó. Các endpoint tác vụ bất đồng bộ (/v1/video/generations, /v1/videos, /suno/*) trả {"code", "message", "data"} cho lỗi phát sinh sau khi định tuyến, và message đó không kèm request id.

401 Unauthorized

API Key bị thiếu, không hợp lệ, đã hết hạn, đã bị vô hiệu hóa hoặc đã dùng hết quota:

Thiếu header Authorization, hoặc không viết dạng Bearer sk-....
Key đã bị xóa, vô hiệu hóa hoặc hết hạn.
Quota còn lại của Key đã hết.
Gửi Management Key (rat_...) tới endpoint mô hình; gọi mô hình phải dùng API Key bắt đầu bằng sk-.

Tạo Key mới trên trang API Keys nếu cần. Quota và thời hạn của Key được mô tả trong Số dư và quota.

403 Forbidden

403 có hai nguyên nhân hoàn toàn khác nhau; trước tiên hãy xem code trong phản hồi.

Thiếu số dư hoặc quota của Key

insufficient_user_quota: số dư tài khoản không đủ chi phí ước tính của yêu cầu này, hoặc gói đăng ký không còn quota.
pre_consume_token_quota_failed: quota còn lại của Key không đủ chi phí ước tính.

Hãy nạp tiền, tăng quota của Key, hoặc giảm max_tokens để chi phí ước tính nằm trong quota. Xem Số dư và quota.

Không đủ quyền

Các lỗi này thường có code rỗng; thông báo cho biết bước kiểm tra nào đã thất bại:

Giới hạn mô hình của Key không bao gồm mô hình này (This token has no access to model ...).
Nhóm của Key không khả dụng với tài khoản của bạn.
IP nguồn không nằm trong danh sách IP cho phép của Key (code là access_denied).
Tài khoản đã bị vô hiệu hóa.

429 Too Many Requests

Đã vượt giới hạn tần suất yêu cầu. Giới hạn tính theo tài khoản: mọi Key trong cùng tài khoản dùng chung quota, nên thêm Key không nâng giới hạn. Yêu cầu bị từ chối không bị tính phí.

Thử lại với exponential backoff kèm jitter ngẫu nhiên.
Giảm đồng thời hoặc trải yêu cầu ra thời gian dài hơn.
Phản hồi 429 có thể có phần thân rỗng; hãy dựa vào mã trạng thái thay vì thông báo.

Cách giới hạn yêu cầu mô hình hoạt động và cách thử lại khi upstream trả 429, xem Usage và tính phí.

503 Mô hình không khả dụng

code là model_not_found cùng thông báo kiểu “No valid upstream service”: hiện không có kênh nào phục vụ mô hình này cho nhóm của bạn. Kiểm tra cách viết Model ID và xem mô hình có mở cho tài khoản của bạn không; thử lại ngay yêu cầu đó thường không giúp ích.

502 / 503 Lỗi upstream

502 hoặc 5xx khác từ nhà cung cấp mô hình được trả nguyên trạng sau khi mọi lần thử lại đều thất bại.
code là get_channel_failed với thông báo “Upstream service is temporarily unavailable”: tài khoản upstream phía sau kênh không dùng được (ví dụ hết số dư hoặc thông tin đăng nhập hết hiệu lực). RouteAPI thử lại qua kênh khác khi có thể, nếu vẫn thất bại thì trả thông báo chung này, phát cảnh báo nội bộ và có thể tự vô hiệu hóa kênh lỗi; hãy thử lại sau.
code là client_failfast (503): cùng một API Key liên tục thất bại với tỷ lệ cao cho mô hình này, nên nền tảng mở cửa sổ bảo vệ ngắn cho cặp Key/mô hình đó. Phản hồi có Retry-After và X-Client-Failfast: 1; hãy chờ rồi thử lại, và sửa nguyên nhân lỗi trước khi gửi lại y hệt.

Lỗi tạm thời thì thử lại sau. Nếu lỗi kéo dài, hãy liên hệ hỗ trợ kèm request id.