> AI 에이전트용: 단계별 설정 안내 — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), 문서 인덱스 — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# 에러 및 제한

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

## 제한

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

| 제한 | 값 | 초과 시 |
| --- | --- | --- |
| 키당 분당 요청 수 | 120, 첫 요청부터 60초 윈도우 | `429 rate_limit_exceeded`와 헤더 `Retry-After`. 게이트웨이의 5xx 거부는 할당량을 소모하지 않습니다 |
| 계정의 동시 요청 수 | 제한됨 | 초과분은 큐에서 대기. 기다리지 못하면 `429 queue_timeout` |
| 요청 본문 크기 | 16 MiB | `413` |
| 출력 길이 | [모델별 — 아래 표 참조](https://gate.joingonka.ai/ko/docs/errors#max-tokens) | 모델 상한을 초과하면 에러 없이 상한까지 잘림 |
| 하위 키 | 관리 키당 최대 50개, 각각 분당 120 요청 | 상한 상향은 지원팀을 통해 |

### 모델별 출력 길이

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

| `model` | 상한 | 비스트리밍 | 스트리밍 |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | 8192 | 1500 | 8192 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | 32768 | 1500 | 32768 |
| `zai-org/GLM-5.3-Flash` | 8192 | 3000 | 8192 |

## 타임아웃

| 단계 | 값 | 발생 내용 |
| --- | --- | --- |
| 큐 대기 | 45초 | `Retry-After: 1` 헤더가 있는 `429 queue_timeout` |
| 네트워크 응답 시작, 스트리밍 | 150초 | `504 upstream_timeout`. 입력 토큰 추정치가 청구됩니다 |
| 네트워크 응답 시작, 비스트리밍 | 150초 | `504 upstream_timeout`. 입력 토큰 추정치가 청구됩니다 |
| 답변 생성 | ≈300초 | 네트워크가 생성을 중단: 응답이 `finish_reason: length`와 함께 반환됩니다. 다음 요청으로 이어가세요 |
| 스트림 청크 간 일시 정지 | 30초 | 스트림이 닫힘: 청크 `joingonka-stream-stalled`의 `finish_reason: stop` |
| 스트림의 연결 유지 신호 | 15초 | 주석 `: keep-alive` — SSE 클라이언트는 이를 건너뜁니다 |
| 스트림 열기 | 30초 | 이 시점까지는 응답 코드로 거부가 반환되고, 이후에는 청크 `joingonka-error`로 반환됩니다 |
| 비스트리밍 조기 응답 | 90초 | 게이트웨이가 `200`를 반환하고 15초마다 공백을 보냅니다 — JSON은 유효하게 유지됩니다. 이후의 에러는 `error` 필드를 포함한 본문으로 반환되며, 상태는 `200`로 유지됩니다 |

> **타임아웃 시 청구 내용**
>
> 네트워크가 수락한 요청은 취소할 수 없습니다. `504 upstream_timeout` 발생 시 입력 토큰 추정치가 청구되고 출력 토큰은 청구되지 않습니다. 재시도는 새로운 청구입니다. 최종 `usage` 전에 중단된 스트림도 동일하게 청구됩니다. 긴 응답이 필요하면 `stream: true`을 사용하세요.

## 오류 코드

오류 본문은 `message, type, code, param` 필드를 가진 `error` 객체입니다. 모든 오류에 모든 필드가 있는 것은 아닙니다. 상태 코드와 `type`을 기준으로 하고, `code`로 세부 사항을 확인하세요. `message` 텍스트는 변경될 수 있습니다. Anthropic 형식은 [Anthropic 오류 형식](https://gate.joingonka.ai/ko/docs/errors#anthropic-errors) 섹션을 참조하세요.

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

| 응답 | 시점 | 대처 방법 |
| --- | --- | --- |
| 400 `invalid_request_error` | 잘못된 요청 본문: `messages` 없음, 메시지가 객체가 아님, 본문이 JSON이 아님. 알 수 없는 모델의 경우 `param`과 함께 `model` 및 사용 가능한 모델 목록이 텍스트에 포함됨 | 오류 메시지에 따라 요청을 수정하세요 |
| 400 `invalid_request_error` `empty_content_after_normalization` | 정규화 후 메시지가 비어 있음 — 예를 들어 이미지만 포함된 경우 | 메시지에 텍스트를 추가하세요 |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | 하나의 요청에 `web` 및 `privacy-sanitization` 플러그인이 함께 있음 | 둘 중 하나만 남기세요 |
| 400 `invalid_request_error` `previous_response_id_not_supported` `conversation_not_supported` `item_reference_not_supported` `background_not_supported` `hosted_tool_choice_not_supported` | OpenAI Responses: 저장된 응답, 대화 또는 항목에 대한 참조, 백그라운드 모드, 내장 도구 요구 | 전체 기록을 `input`에 담아 보내세요 |
| 400 `api_error` | 네트워크가 매개변수를 거부 — 예를 들어 `reasoning_effort` 값이 네트워크 목록에 없는 경우 | 오류 메시지에 따라 값을 수정하세요 |
| 401 `authentication_error` | 키를 찾을 수 없거나, 취소되었거나, 알 수 없는 형식 | [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) 페이지에서 키를 확인하세요 |
| 402 `insufficient_funds` | 요청 추정치에 비해 잔액이 부족합니다. 잔액은 `balance_ngonka`에 있습니다 | 잔액을 충전하세요: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | 사이트가 아닌 곳에서의 키 없는 요청 (`is_demo: true`) | API 키를 전달하세요 |
| 402 `child_key_limit_exceeded` | 키의 지출 한도 초과 — 일일, 월간 또는 누적. 잔여량은 `daily_remaining, monthly_remaining, total_remaining`에 있습니다 | [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) 페이지에서 키 한도를 높이거나 초기화를 기다리세요 |
| 403 `forbidden` | 모델 요청에 관리 키 `gm-` 사용. 계정 전용 라우트에 API 키 사용 | 요청에는 `jg-` 또는 `gc-` 키를 사용하세요. 계정 관리는 대시보드에서 하세요 |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: 모델이 카탈로그에 없거나 일시적으로 숨겨져 있음 | `GET /v1/models`에서 id를 가져오세요 |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` 및 기타 상태 주소, `/v1/responses/compact` | 기록을 직접 보관하세요. Codex CLI의 경우 자체 프로바이더 id를 설정하세요 |
| 404 `invalid_request_error` | 알 수 없는 경로 | 메서드, 경로 및 기본 주소를 확인하세요 |
| 413 `invalid_request_error` | 요청 본문이 한도를 초과함 | 요청을 줄이세요 |
| 415 `invalid_request_error` | 헤더에 따르면 본문이 JSON이 아님: `Content-Type: application/json` 필요 | `Content-Type: application/json`를 전송하세요 |
| 429 `rate_limit_exceeded` | 키당 분당 요청 수 초과. 본문에 `limit, remaining, reset`을 포함한 `rate_limit`이 있음 | `Retry-After`에 표시된 초만큼 기다리세요 |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Gonka 네트워크에서 모델이 과부하 상태입니다 | `Retry-After` 후에 재시도하거나 다른 모델을 사용하세요 — [모델](https://gate.joingonka.ai/ko/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | 네트워크의 모든 슬롯이 사용 중: 대기열이 가득 찼거나 대기 시간이 초과됨 | `Retry-After` 후에 재시도하세요 |
| 500 `server_error` | 게이트웨이 내부 오류 | 나중에 재시도하세요. 반복되면 `x-request-id`를 첨부하여 지원팀에 문의하세요 |
| 501 `not_implemented` | `POST /v1/embeddings`: 네트워크에 임베딩 모델이 없음 | 다른 임베딩 서비스를 이용하세요 |
| 502 `api_error` `upstream_unauthorized` | 네트워크 프로바이더가 게이트웨이 자격 증명을 거부함 — 고객님의 키는 정상입니다 | 1분 후에 재시도하세요 |
| 502 `api_error` | Gonka 네트워크 오류. `code`는 네트워크가 전송한 경우 네트워크 측 정보입니다 | 간격을 두고 재시도하거나 다른 모델을 사용하세요 |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | 네트워크 프로브 결과 모델을 현재 사용할 수 없음: 장애, 시작 중, 불안정 또는 아무도 서비스를 제공하지 않는 상태. 대기 없이 즉시 거부됨 | 다른 모델을 사용하세요 — 오류 메시지가 어떤 모델인지 알려줍니다. 목록은 [모델](https://gate.joingonka.ai/ko/docs/models) |
| 503 `service_unavailable` | 사용 가능한 노드가 없음 | 나중에 재시도하세요 |
| 504 `timeout` `upstream_timeout` | 네트워크가 요청을 수락했지만 제때 응답하지 않음. 입력 토큰 추정치가 청구되었습니다 | 긴 응답에는 `stream: true`을 사용하세요. 재시도는 새로운 청구입니다 |

## 열린 스트림 내 오류

스트림이 열리기 전에는 비스트리밍과 동일하게 일반 응답 코드로 거부가 전달됩니다. 열린 후에는 상태가 이미 `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]`.

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

## Anthropic 오류 형식

- `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`.

```text
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`를 첨부하여 지원팀에 문의하세요.