Mã lỗi và thử lại

Khi xảy ra lỗi, giao diện trả về mã trạng thái không phải 2xx, phần thân phản hồi là JSON:

{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": "..."
  }
}

Mã lỗi thường gặp

HTTP 状态	Nguyên nhân thường gặp	Cách xử lý được khuyến nghị
400	Lỗi tham số, định dạng body yêu cầu không hợp lệ	Kiểm tra lại tham số và định dạng JSON
401	Thiếu khóa / không hợp lệ	Kiểm tra `Authorization: Bearer sk-...`
403	Token bị vô hiệu hóa, nhóm mô hình không có quyền truy cập	Kiểm tra trạng thái token và nhóm trong bảng điều khiển
404	Tên mô hình không tồn tại hoặc chưa được mở	Xem Tổng quan mô hình
413	Body yêu cầu quá lớn (vượt quá giới hạn ngữ cảnh)	Rút gọn messages hoặc dùng mô hình có ngữ cảnh dài hơn
429	Bị giới hạn tốc độ hoặc không đủ hạn mức	Thử lại theo backoff, xem Giới hạn tốc độ và 429
500 / 502 / 503	Biến động từ upstream mô hình	Thử lại sau khi backoff ngắn, gateway sẽ tự động chuyển sang upstream khả dụng

Với 429 / 5xx, áp dụng exponential backoff + jitter: ví dụ 1s, 2s, 4s, tối đa 3–5 lần;
400 / 401 / 403 là lỗi mang tính xác định, thử lại không có ý nghĩa, cần sửa yêu cầu trước;
Với các trường hợp idempotent (như tạo hình ảnh), trước khi gửi lại hãy xác nhận trạng thái cuối cùng của lần yêu cầu trước để tránh bị trừ phí lặp;
Môi trường production nên ghi lại response header và error.message, để dễ xác định lỗi được trả về từ khâu nào.