Dành cho AI agent: hướng dẫn từng bước để thiết lập — /docs/agents.md, chỉ mục tài liệu — /llms.txt.

Lỗi và giới hạn

Giới hạn yêu cầu, thời gian chờ và mã lỗi của gateway. Với mỗi phản hồi, chúng tôi nêu rõ khi nào nó xảy ra và cần làm gì: thử lại yêu cầu hay sửa lại yêu cầu.

Các con số — từ trường limits trong phản hồi GET /v1/capabilities: ở đó luôn có giá trị mới nhất.

Độ dài phản hồi theo model#

Không có max_tokens, gateway sẽ dùng giá trị mặc định: không streaming — ngắn hơn, để phản hồi kịp trong thời gian timeout, khi streaming — mức trần của model. max_completion_tokens — cùng một trường.

Phần thân lỗi là một đối tượng error với các trường message, type, code, param; không phải lỗi nào cũng có đủ các trường. Hãy dựa vào trạng thái và type, đối chiếu thêm bằng code: nội dung message có thể thay đổi. Định dạng Anthropic nằm ở mục Định dạng lỗi Anthropic.

{
  "error": {
    "message": "Model is currently overloaded in the Gonka network",
    "type": "rate_limit_exceeded",
    "code": "upstream_rate_limited"
  }
}

Khi luồng chưa mở, lỗi từ chối đến dưới dạng mã phản hồi thông thường — như khi không dùng stream. Sau khi mở, trạng thái đã là 200, và lỗi đến như sau:

• Chat Completions — chunk joingonka-error với trường error, rồi ngắt kết nối mà không có [DONE].
• Không dùng stream sau phản hồi sớm — trạng thái 200 và thân có trường error.
• Anthropic Messages — sự kiện event: error, rồi luồng đóng lại.
• OpenAI Responses — sự kiện response.failed, nguyên nhân ở response.error.code.
• Legacy Completions — data: {"error": …}, rồi [DONE].

data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}

• POST /v1/messages phản hồi bằng envelope Anthropic: {"type": "error", "error": {"type", "message"}}.
• Lỗi từ chối của gateway giữ nguyên type từ bảng trên (insufficient_funds, model_unavailable và các loại khác); không có trường code trong envelope này — nguyên nhân nằm trong nội dung.
• Lỗi hình thức yêu cầu — invalid_request_error: thiếu message hoặc max_tokens, gọi công cụ không có tên, model không xác định.
• Đường dẫn không xác định — not_found_error, thân quá lớn — request_too_large.

event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}

• Sau khoảng nghỉ trong Retry-After: 429
• Với khoảng nghỉ tăng dần — 1, 2, 4 giây và tiếp tục: 500, 502, 503 service_unavailable, 504
• Với model khác: 503 model_unavailable
• Không thử lại nguyên trạng — hãy sửa yêu cầu, key hoặc số dư: 400, 401, 402, 403, 404, 413, 415, 501

Mỗi lần thử lại sau 504 là một lần trừ mới cho ước tính đầu vào; với câu trả lời dài, hãy bật stream: true.

Lỗi lặp lại — hãy liên hệ hỗ trợ và kèm x-request-id từ header phản hồi.