AI 에이전트용: 단계별 설정 안내 — /docs/agents.md, 문서 인덱스 — /llms.txt.

에러 및 제한

게이트웨이의 요청 제한, 타임아웃, 오류 코드. 각 응답이 언제 발생하는지, 그리고 어떻게 대처해야 하는지(요청 재시도 또는 수정)를 설명합니다.

수치는 응답 GET /v1/capabilities의 limits 필드에서 가져옵니다. 항상 최신 값이 기재되어 있습니다.

모델별 출력 길이#

max_tokens를 지정하지 않으면 게이트웨이가 기본값을 적용합니다. 비스트리밍에서는 타임아웃 내에 응답하도록 더 짧게, 스트리밍에서는 모델 상한으로. max_completion_tokens는 동일한 필드입니다.

오류 본문은 message, type, code, param 필드를 가진 error 객체입니다. 모든 오류에 모든 필드가 있는 것은 아닙니다. 상태 코드와 type을 기준으로 하고, code로 세부 사항을 확인하세요. message 텍스트는 변경될 수 있습니다. Anthropic 형식은 Anthropic 오류 형식 섹션을 참조하세요.

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

스트림이 열리기 전에는 비스트리밍과 동일하게 일반 응답 코드로 거부가 전달됩니다. 열린 후에는 상태가 이미 200이며 오류는 다음과 같이 전달됩니다:

• Chat Completions — error 필드를 가진 joingonka-error 청크, 이후 [DONE] 없이 연결이 끊어집니다.
• 조기 응답 후 비스트리밍 — 상태 200 및 error 필드를 가진 본문.
• Anthropic Messages — event: error 이벤트, 이후 스트림이 닫힙니다.
• OpenAI Responses — response.failed 이벤트, 원인은 response.error.code에 있습니다.
• Legacy Completions — data: {"error": …}, 이후 [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는 Anthropic 엔벨로프로 응답합니다: {"type": "error", "error": {"type", "message"}}.
• 게이트웨이 거부는 위 표의 type을 유지합니다 (insufficient_funds, model_unavailable 등). 이 엔벨로프에는 code 필드가 없으며 원인은 텍스트에 있습니다.
• 요청 형식 오류 — invalid_request_error: 메시지 또는 max_tokens 없음, 이름 없는 도구 호출, 알 수 없는 모델.
• 알 수 없는 경로 — not_found_error, 본문이 너무 큼 — request_too_large.

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

• Retry-After에 표시된 대기 후: 429
• 지수 백오프 — 1, 2, 4초 이후: 500, 502, 503 service_unavailable, 504
• 다른 모델로: 503 model_unavailable
• 변경 없이 재시도하지 마세요 — 요청, 키 또는 잔액을 수정하세요: 400, 401, 402, 403, 404, 413, 415, 501

504 이후 각 재시도는 입력 추정치의 새로운 청구입니다. 긴 응답에는 stream: true을 활성화하세요.

오류가 반복되면 응답 헤더의 x-request-id를 첨부하여 지원팀에 문의하세요.