# 에러

> 상태 코드와 대응 방법, 그리고 증상별로 찾아가는 자리.

> 원문: https://oneport.kr/docs/errors

에러 몸통은 부르신 문의 형식을 따라요 — OpenAI 형식 문과 /v1/messages 의 모양이 다르니 파서를 짜실 때 보세요. 어느 쪽이든 type 값은 같아요.

**OpenAI 형식 문 (/v1/chat/completions · /v1/responses · /v1/embeddings 등)**

```json
{
  "error": {
    "type": "model_not_found",
    "message": "지원하지 않는 모델이에요: claude-sonet-5. 이건 어떠세요: claude-sonnet-5. 전체 목록은 GET /v1/models 에 있어요.",
    "code": "model_not_found"
  }
}
```

**Anthropic 형식 문 (/v1/messages)**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "이 문은 anthropic 모델만 받아요."
  }
}
```

| 코드 | type | 뜻과 대응 |
| --- | --- | --- |
| 400 | invalid_request_error | 요청 형식이나 문이 안 맞아요. 파는 모델인데 문이 틀린 경우도 여기로 와요 — 그때는 어느 문으로 가야 하는지 문장에 적어 드려요. |
| 401 | authentication_error | 키가 없거나 폐기됐어요. Authorization: Bearer 또는 x-api-key 헤더를 확인해주세요. |
| 402 | insufficient_credit | 크레딧이 모자라요. 부르기 전에 나오니 요금은 안 붙어요. |
| 403 | model_not_in_plan | 이 크레딧으로 못 부르는 모델이에요 — 제미나이는 제미나이 팩이나 모델을 정하지 않은 크레딧으로 불러요. 요금이 붙기 전에 나고, 바꿔 넣을 모델 이름을 문장에 같이 드려요. |
| 404 | model_not_found | 그 이름의 모델이 없어요. 응답에 가장 가까운 이름을 같이 드려요. |
| 429 | key_limit_exceeded | 그 키의 이번 달 한도에 닿았어요. 대시보드에서 올리시면 바로 풀려요. 분당 제한은 저희가 안 걸어요. |
| 502 | upstream_error | 벤더가 실패했어요. 저희가 다른 경로로 다시 걸어봤는데도 안 된 경우예요. |
| 503 | api_error | 저희 쪽 일시 장애예요. 잠시 후 다시 시도해주세요. |

## 402 는 호출 전에 나요

게이트웨이는 부르기 전에 이 요청이 최대로 쓸 금액을 미리 잡아둬요. 잔액이 그보다 적으면 벤더로 보내지 않고 402 를 돌려줘요. 그래서 max_tokens 를 크게 잡으면 잔액이 남아 있어도 막힐 수 있어요 — 줄이면 통과해요.

## 폴백 — 한 번 실패해도 저희가 다시 걸어요

429 나 5xx 가 나면 같은 모델을 다른 경로로 다시 시도해요. 몇 번째에 성공했는지는 응답 헤더 x-gateway-fallback-depth 에 담겨요. 400 이나 404 처럼 다시 보내도 같을 실패는 재시도하지 않고 그대로 돌려드려요.

## 자주 만나는 실패

| 무엇을 했을 때 | 오는 값 | 저희가 하는 일 |
| --- | --- | --- |
| 없는 모델 이름 | 404 · model_not_found | 가장 가까운 이름을 같이 드려요. 시키지 않은 모델로 몰래 바꾸지 않아요. |
| 그림 모델을 채팅 문으로 | 400 · invalid_request_error | 「없다」고 하지 않고 어느 문으로 가야 하는지 문장에 적어 드려요. |
| Claude 5 에 temperature | 400 (직접 부르실 때만) | /v1/chat/completions 로 부르시면 저희가 빼고 넘겨서 안 나요. |
| 잔액보다 큰 max_tokens | 402 · insufficient_credit | 벤더로 안 보내요. 요금이 안 붙으니 값을 줄여 다시 보내시면 돼요. |
| 클로드·GPT 팩 크레딧으로 제미나이 | 403 · model_not_in_plan | 벤더로 안 보내고 요금도 안 붙어요. 부를 수 있는 모델 이름을 같이 드려요. |
| 벤더가 잠시 조임 | 보통 안 보여요 | 같은 모델의 다른 경로로 다시 걸어요. 몇 번째에 됐는지 x-gateway-fallback-depth 에 담겨요. |
| 모든 경로가 실패 | 502 · upstream_error | 더 시도할 곳이 없을 때만 드려요. 잠시 후 다시 보내주세요. |

## 증상별로 찾기

> **⚠️ Anthropic SDK·Claude Code 에서 404 가 나나요**
>
> base_url 끝에 /v1 을 붙이셨을 거예요. Anthropic SDK 는 /v1/messages 를 스스로 붙이기 때문에 /v1/v1/messages 로 나가요. base_url 은 https://oneport.kr 까지만 적어주세요. 반대로 OpenAI SDK 는 /v1 이 필요해요.

> **⚠️ 모델 이름은 맞는데 400 이 나나요**
>
> 문이 틀렸을 가능성이 커요. 그림 모델을 채팅 문으로, pro 등급을 /v1/chat/completions 로 부르면 그래요. 저희는 「없다」고 하지 않고 어느 문으로 가야 하는지 문장에 적어 드리니 그 문장을 보세요. 종류별 문은 GET /v1/models 의 endpoint 칸에도 있어요.

> **⚠️ temperature 를 보냈더니 400 이 나나요**
>
> Claude 5 세대를 /v1/messages 로 직접 부르셨거나 GPT 를 부르셨을 거예요. Claude 는 /v1/chat/completions 로 부르시면 저희가 그 값을 빼고 넘겨서 400 이 안 나요 — 어차피 모델이 안 읽는 값이라 답은 같아요. GPT(5 이후 대부분·o 계열)는 어느 문으로 부르셔도 기본값 1 말고는 벤더가 거절해요 — temperature 를 빼고 보내주세요.

> **⚠️ 403 model_not_in_plan 이 나나요**
>
> 클로드·GPT 팩으로 사신 크레딧으로 제미나이를 부르셨어요 — 제미나이는 제미나이 팩이나 모델을 정하지 않은 크레딧으로 불러요. 오류 문장에 적힌 모델 이름으로 바꾸시거나, 같은 키로 GET /v1/models 를 불러 부를 수 있는 모델을 보세요. 요금은 안 붙었어요.

> **⚠️ max_tokens 를 보냈더니 400 이 나나요**
>
> GPT-5 이후와 o 계열은 max_tokens 라는 이름을 안 받아요. max_completion_tokens 로 바꿔 보내주세요 — 뜻은 같아요. Claude 는 둘 다 받아요(저희가 Anthropic 이름으로 옮겨요).

> **⚠️ GPT 에 도구를 붙였더니 400 이 나나요**
>
> GPT-5.6·GPT-6 는 /v1/chat/completions 에서 도구와 추론을 같이 못 써요. reasoning_effort 를 "none" 으로 같이 보내시거나(추론을 끄는 대신), 추론까지 필요하시면 /v1/responses 로 보내주세요. GPT-6 Astra·GPT-6.1 Sol 은 none 이 없어서 도구는 /v1/responses 로만 돼요.

> **⚠️ reasoning_effort 를 줬는데 아무 차이가 없나요**
>
> 받는 모델인지부터 보세요 — GET /v1/models 의 supports_effort 가 알려드려요. 받는 모델인데도 차이가 없으면 알려주세요. 2026-09-01 까지 저희가 Claude 로 갈 때 이 값을 조용히 버리고 있었고, 지금은 Anthropic 이 실제로 받는 자리로 옮겨서 넘겨요.

> **⚠️ 긴 답을 받다가 연결이 끊기나요**
>
> 한 호출을 기다리는 시간에 상한이 있어요 — 글은 5분, 그림·받아쓰기는 2분이에요. 스트리밍도 같은 시계를 써요. 아주 긴 답이 필요하시면 stream 을 켜서 받는 대로 쓰시거나, 요청을 나눠 보내주세요. pro 등급은 한 답에 수십 초가 걸리니 클라이언트 타임아웃도 넉넉히 잡아주세요.

> **그래도 안 풀리면**
>
> 응답 헤더의 x-gateway-fallback-depth 값과 부르신 모델 이름을 알려주시면 저희 쪽 기록에서 그 호출을 찾을 수 있어요. admin@schoolorder.kr 로 보내주세요.