MenuGiới hạn & mã lỗi

/

Giới hạn & mã lỗi

API dùng mã trạng thái HTTP tiêu chuẩn. Body lỗi theo định dạng client bạn dùng, nên SDK OpenAI và Anthropic có thể đọc nguyên trạng.

Định dạng lỗi

Endpoint định dạng OpenAI trả về đối tượng error gồm message, type và code. Endpoint định dạng Anthropic trả về "type": "error" cùng đối tượng error gồm type và message. Lỗi xảy ra giữa stream được gửi dưới dạng event có cùng cấu trúc.

402

{
  "error": {
    "message": "GeraiPoints tidak cukup, silakan top up",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

Nội dung message được viết bằng tiếng Indonesia và có thể thay đổi. Với logic chương trình, hãy kiểm tra mã trạng thái HTTP và type/code, không dựa vào nội dung thông báo.

Mã trạng thái

Mã	type / code	Ý nghĩa	Cần làm gì
400	`invalid_request_error`	Request không hợp lệ: body không phải JSON, `model` trống, hoặc `messages` thiếu/trống. Cũng xảy ra khi base URL sai khiến path thành `/v1/v1/…`.	Kiểm tra body và base URL.
401	`authentication_error`	API key không được gửi, sai hoặc đã bị thu hồi — hoặc dùng nhầm luồng (key bansos ở endpoint trả phí, và ngược lại).	Kiểm tra key và base URL — Xác thực.
402	`insufficient_quota`	Không đủ GeraiPoints cho request này.	Nạp GeraiPoints rồi gửi lại.
403	`permission_error`	Model không có trong allowlist của key này, hoặc là model dành riêng cho gói mà bạn chưa có.	Thêm model vào allowlist của key, hoặc dùng key khác.
404	`model_not_found`	Id model không xác định hoặc hiện không mở. Tên có prefix như `gp/…` hoặc `openai/…` cũng trả về 404.	Sao chép đúng id từ danh sách model.
413	`—`	Body request quá lớn để máy chủ tiếp nhận.	Rút gọn lịch sử hội thoại hoặc giảm tệp đính kèm.
429	`rate_limit_error`	Quá nhiều request: model đang đầy công suất, hoặc đã vượt giới hạn của gói Unlimited/Bansos.	Chờ theo `Retry-After` (nếu có), rồi thử lại với khoảng nghỉ.
502	`api_error`	Dịch vụ model đang bận hoặc gặp sự cố; request không bị tính phí.	Thử lại sau vài giây, hoặc dùng model khác.
503	`api_error`	Model đang bảo trì hoặc tạm thời không khả dụng; request không bị tính phí.	Thử lại sau hoặc dùng model khác.

Giới hạn sử dụng

Loại	Giới hạn
Key trả phí (gk-)	Không có giới hạn tốc độ cố định cho mỗi key; mức dùng bị giới hạn bởi số dư GeraiPoints. 429 chỉ xuất hiện khi model đang đầy công suất.
Unlimited plan	Giới hạn số request mỗi phút và số request đồng thời cho mỗi tài khoản. Phản hồi 429 kèm `Retry-After` và `x-ratelimit-*`. Chi tiết ở trang Unlimited.
Gói miễn phí (Bansos)	Hạn mức request mỗi ngày và giới hạn mỗi phút. Phản hồi 429 kèm `Retry-After` và `x-ratelimit-*`. Hạn mức còn lại ở trang Bansos.
Kích thước & câu trả lời	Body quá lớn bị từ chối với 413. Độ dài câu trả lời (`max_tokens`) có thể tự động giảm nếu số dư không đủ cho giá trị yêu cầu.
API key	Tối đa 20 key đang hoạt động mỗi tài khoản; allowlist tối đa 64 model mỗi key.
Khóa khách hàng	Giới hạn được áp dụng trước khi xử lý: yêu cầu vượt quá phần còn lại sẽ bị từ chối. Hết giới hạn một lần → `402 KEY_BATAS_HABIS` (tăng giới hạn để thêm hạn mức); chạm giới hạn ngày/tháng → `429 KEY_BATAS_HARIAN` / `KEY_BATAS_BULANAN` kèm `Retry-After`. Key tạm dừng → `403 KEY_DIJEDA`. Mô hình -unli và bansos không dùng được với khóa khách hàng.

Thử lại đúng cách

Chỉ thử lại với 429, 502 và 503, với khoảng chờ tăng dần (ví dụ 1, 2, 4, 8 giây) và tối đa 2–3 lần.
Không thử lại với 400, 401, 402, 403, 404 — hãy sửa request trước; kết quả sẽ vẫn như cũ.
Tuân theo header Retry-After nếu có.
Mỗi lần thử lại là một request mới bị tính phí. Nếu nguyên nhân là timeout của ứng dụng, hãy tăng timeout — xem Cài đặt công cụ agentic.