Lỗi & giới hạn

Mọi lỗi trả về theo định dạng của chuẩn bạn đang dùng, kèm header x-request-id để tra cứu với hỗ trợ.

Định dạng lỗi

OpenAI surface

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Anthropic surface

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "..."
  }
}

Bảng mã

HTTP	Code	Nghĩa & xử lý
400	`invalid_request_error`	Body sai schema, tham số không hợp lệ với model. Sửa request.
401	`invalid_api_key`	Key sai, không tồn tại hoặc đã bị thu hồi.
403	`key_suspended`	Key bị tạm ngưng — liên hệ hỗ trợ.
403	`key_expired`	Key hết hạn — liên hệ nơi bán để gia hạn.
403	`package_disabled`	Gói của key đang bị vô hiệu.
404	`model_not_found`	Model không tồn tại hoặc gói của bạn không được phép dùng.
413	`request_too_large`	Body vượt giới hạn của gói.
429	`rate_limit_exceeded`	Vượt requests/phút hoặc số request đồng thời. Đợi theo `Retry-After`.
429	`quota_exceeded`	Hết hạn mức ngày/tháng/tổng. Xem /usage.
502	`upstream_error`	Nhà cung cấp phía sau lỗi. Thử lại.
502	`provider_unavailable`	Nhà cung cấp tạm thời không phục vụ được. Thử lại sau.
503	`service_unavailable`	Nền tảng tạm thời không sẵn sàng.
504	`upstream_timeout`	Nhà cung cấp phản hồi quá lâu.

Retry-After

Response 429 kèm header Retry-After (giây). Với giới hạn requests/phút, giá trị là số giây còn lại của phút hiện tại. Với hạn mức ngày/tháng, giá trị là con số thận trọng — hãy xem /usage để biết mốc reset thật (theo UTC).

Cách tính hạn mức

Ngày và tháng theo UTC; tháng theo lịch, không phải 30 ngày trượt.
Chỉ request được chấp nhận mới trừ hạn mức. Request bị chặn vì key sai, hết hạn, model không được phép, hoặc vượt giới hạn không trừ quota.
Token tính theo số liệu nhà cung cấp trả về. Nếu nhà cung cấp không trả usage, nền tảng ghi 0 token thay vì tự ước lượng.

Streaming bị lỗi giữa dòng

Khi kết nối đã mở (HTTP 200) mà upstream lỗi, nền tảng không thể đổi mã HTTP. Thay vào đó một event lỗi theo đúng định dạng chuẩn được phát ra trước khi đóng stream. Client nên kiểm tra event lỗi, đừng chỉ nối text delta.