에러

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

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

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

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

Anthropic 형식 문 (/v1/messages)

{
  "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	더 시도할 곳이 없을 때만 드려요. 잠시 후 다시 보내주세요.

증상별로 찾기#

이 문서를 AI 에게 넘기시려면 마크다운 원문을 쓰세요 — 주소 끝에 .md 를 붙이면 나와요.