오류 형식
/v1 엔드포인트에서 오류가 나면 4xx / 5xx 상태 코드와 함께 아래 예시 같은 JSON을 돌려줍니다. message는 사람이 읽는 설명, type은 오류의 큰 분류, code는 바뀌지 않는 기계 판독용 식별자, param은 문제가 된 필드(없으면 null)입니다. HTTP 상태 코드와 code로 판단하고, message 문구로는 판단하지 마세요. 영어, 중국어 또는 둘 다일 수 있고 문구도 바뀝니다.
HTTP 402 · /v1
{
"error": {
"message": "Insufficient balance — please top up",
"type": "insufficient_quota",
"code": "insufficient_quota",
"param": null
}
}/anthropic 엔드포인트는 Anthropic 고유의 형식을 따르며 code와 param이 없습니다. HTTP 상태 코드와 error.type으로 판단하세요:
HTTP 404 · /anthropic
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "model: gpt-5.5"
}
}
- 일부 오류에는 최상위 필드가 더 붙습니다. 예를 들어 모든 회선이 가득 찼을 때는
attempts, 잠시 쓸 수 있는 회선이 없을 때는 retry_after가 붙습니다. 모르는 필드는 무시하면 됩니다.
- 모델 제공사가 요청을 거부하면(예: 컨텍스트가 너무 긴 경우)
message에는 모델 제공사의 원래 문구가, code에는 모델 제공사가 준 값이 들어가며, 값을 주지 않았으면 invalid_request입니다.
HTTP 상태 코드 한눈에 보기
| HTTP | 언제 나오나요 |
|---|
| 400 | 잘못된 파라미터 또는 없는 모델(model_not_found 등). error.param이 해당 필드를 알려 줍니다. |
| 401 | 키가 없거나, 유효하지 않거나, 정지된 키(missing_api_key, invalid_api_key). |
| 402 | 잔액이 부족하거나 키가 예산 한도에 도달했습니다(insufficient_quota). |
| 403 | 이 키의 모델 허용 목록에 해당 모델이 없거나, 키의 IP 허용 목록 밖에서 온 요청입니다(permission_denied). |
| 404 | 경로가 없거나, 작업 ID가 없거나 3일 기록 보관 기간이 지났거나 다른 계정이 제출한 작업입니다(job_not_found). |
| 429 | 이 키에 설정한 분당 요청 수나 무료 모델의 하루 한도를 넘었거나, 이 모델의 모든 회선이 가득 찼습니다(rate_limit_exceeded). Retry-After가 있으면 그 초만큼, 없으면 몇 초 기다린 뒤 다시 시도하세요. |
| 502 | 업스트림 오류 또는 시간 초과로, 회선을 바꿔도 실패했습니다. 이유는 code(upstream_timeout, upstream_unavailable 등)에 있습니다. 과금되지 않으니 다시 시도해도 됩니다. |
| 503 | 모델 점검 중(model_maintenance)이거나 당사 측의 일시적인 오류(service_unavailable)입니다. 과금되지 않으니 잠시 후 다시 시도하세요. |
전체 오류 코드
게이트웨이가 돌려주는 오류를 분류별로 정리했습니다. HTTP 상태 코드 하나에 여러 코드가 있을 수 있으니 code를 기준으로 판단하세요.
인증과 계정
| HTTP | code | 원인 | 조치 |
|---|
| 401 | missing_api_key | Authorization: Bearer 헤더가 없습니다. /v1 엔드포인트는 x-api-key를 읽지 않습니다. | Authorization: Bearer YOUR_API_KEY를 추가하세요. |
| 401 | invalid_api_key | 키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다. | 콘솔의 「API Keys」 페이지에서 이 키를 확인하세요. |
| 402 | insufficient_quota | 계정 잔액을 모두 썼습니다(허용된 마이너스 한도보다 낮음). | 충전한 뒤 다시 시도하세요. |
| 403 | permission_denied | 요청이 이 키의 IP 허용 목록 밖에서 왔습니다. | 허용된 IP에서 호출하거나, 콘솔에서 허용 목록을 수정하세요. |
키에 설정한 제한
| HTTP | code | 원인 | 조치 |
|---|
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). Retry-After 헤더는 붙지 않습니다. | 몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요. |
| 429 | rate_limit_exceeded | 무료 모델의 하루 한도를 다 썼습니다(계정별, UTC 기준 하루). message에 대신 쓸 수 있는 유료 모델이 추천될 수 있습니다. | UTC 0시 이후에 다시 쓰거나, 유료 모델로 바꾸세요. |
| 402 | insufficient_quota | 이 키의 일일 예산(UTC 기준 하루) 또는 총 사용 한도를 다 썼습니다. | 다음 날 다시 쓰거나, 콘솔에서 한도를 올리세요. |
| 403 | permission_denied | 이 모델이 키의 모델 허용 목록에 없습니다. | 허용 목록에 있는 모델을 쓰거나, 콘솔에서 허용 목록을 수정하세요. |
요청 자체의 문제
| HTTP | code | 원인 | 조치 |
|---|
| 400 | invalid_json / invalid_encoding | 요청 본문이 올바른 JSON이 아닙니다. UTF-8 인코딩이 아니면 invalid_encoding입니다. | JSON 문법과 인코딩을 확인하세요. |
| 400 | invalid_request | 파라미터가 올바르지 않습니다. 요청 본문이 JSON 객체가 아니거나, n이 정수가 아니거나, 참조 이미지나 참조 영상을 읽을 수 없거나(message에 몇 번째인지와 이유가 적혀 있습니다), /v1/images/edits에 참조 이미지가 없거나, 영상의 길이 / 해상도 / 비율 / 참조 소재 수가 모델이 허용하는 범위를 벗어난 경우 등입니다. | message에 적힌 대로 고친 뒤 다시 제출하세요. |
| 400 | invalid_messages / invalid_role / invalid_max_tokens | 채팅 요청의 messages가 없거나 비어 있거나 형식이 잘못되었거나, role이 허용된 값이 아니거나, max_tokens가 양의 정수가 아닙니다. 문제가 된 필드는 param에 표시됩니다. | param이 가리키는 필드를 고치세요. |
| 400 | missing_prompt | /v1/images/generations 요청에 prompt가 없습니다. | prompt를 추가하세요. |
| 400 | unsupported_resolution | 이 모델은 선택한 해상도 등급을 제공하지 않습니다(예: Grok 이미지 생성에는 4K가 없습니다). | 다른 등급을 고르세요. 모델별로 지원하는 등급은 각 모델 문서에 있습니다. |
| 400 | invalid_callback_url | callback_url이 공개된 http(s) 주소가 아니거나 2000자를 넘습니다. | 인터넷에서 접근할 수 있는 주소를 쓰세요. |
| 400 | max_tokens_too_small | 추론 모델이 max_tokens를 모두 사고에 써서 답변을 쓰지 못했습니다(비스트리밍 채팅). | max_tokens를 늘린 뒤 다시 시도하세요. |
| 404 | not_found | 엔드포인트 경로가 없습니다. | 경로를 확인하세요. 전체 엔드포인트는 API 레퍼런스에 있습니다. |
| 404 | job_not_found | 작업 ID가 없거나, 3일 기록 보관 기간이 지났거나, 다른 계정이 제출한 작업입니다. 이미지 작업을 영상 조회 엔드포인트로 조회할 때(또는 그 반대)도 이 오류가 납니다. | 작업 ID와 조회 엔드포인트를 확인하세요. 결과 링크는 60일 동안 유지되며, 작업 기록이 만료되어도 영향을 받지 않습니다. |
모델 상태
| HTTP | code | 원인 | 조치 |
|---|
| 400 | model_not_found | 모델 ID의 철자가 틀렸거나, model이 없거나, 이 엔드포인트에서 쓸 수 없는 모델입니다(예: 이미지 엔드포인트에 채팅 모델을 지정한 경우). | GET /v1/models 또는 API 레퍼런스에 있는 모델 ID를 쓰세요. |
| 400 | model_disabled | 판매가 끝난 모델입니다. | 다른 모델로 바꾸세요. 대체 모델이 있으면 기존 모델의 페이지가 그 모델로 자동 이동합니다. |
| 400 | model_coming_soon | 공개는 되었지만 아직 호출할 수 없는 모델입니다. | 출시 공지를 기다려 주세요. |
| 503 | model_maintenance | 모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다. | 점검이 끝나면 다시 시도하세요. 진행 상황은 서비스 상태에서 볼 수 있습니다. |
용량과 크레딧 예약
| HTTP | code | 원인 | 조치 |
|---|
| 402 | insufficient_quota | 이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다. | 동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요. |
| 429 | rate_limit_exceeded | 이 모델의 모든 회선이 가득 차서 요청을 보내지 못했습니다. 채팅 엔드포인트에서만 나오며, 이미지와 영상 작업은 거절되지 않고 대기열에서 기다립니다. OpenAI 호환 엔드포인트는 Retry-After를 붙입니다. | Retry-After의 초만큼 기다린 뒤 다시 시도하세요. |
| 503 | service_unavailable | 참조 소재 저장 실패처럼 당사 측에서 일시적인 오류가 났습니다. /v1/responses는 잠시 쓸 수 있는 회선이 없을 때도 Retry-After와 함께 503을 돌려줍니다. | 잠시 후 다시 시도하세요. |
업스트림 오류(채팅 엔드포인트)
채팅 엔드포인트(/v1/chat/completions, /v1/responses, /anthropic/v1/messages)에서 오류가 나면 게이트웨이가 먼저 다른 회선으로 재시도하고, 모든 회선이 실패했을 때만 아래 오류 중 하나를 돌려줍니다. 이 오류들은 모두 과금되지 않습니다.
| HTTP | code | 원인 | 조치 |
|---|
| 502 | upstream_timeout | 회선이 시간 초과되었습니다. 첫 토큰이 너무 늦게 오는 경우도 포함됩니다. | 다시 시도하세요. 긴 답변에는 stream: true를 쓰세요. |
| 502 | upstream_unavailable | 회선에 오류가 났거나 잠시 쓸 수 없습니다. | 잠시 후 다시 시도하세요. |
| 502 | upstream_busy | 모델 제공사가 요청 빈도를 제한하고 있습니다. 모델 제공사의 429는 그대로 전달되지 않고 이 502로 바뀌어 돌아옵니다. | 잠시 후 다시 시도하세요. |
| 502 | upstream_connection_error | 모델 제공사와의 연결이 끊겼습니다. | 다시 시도하세요. |
| 502 | empty_completion | 모델 제공사가 빈 내용을 돌려주었습니다. 요청 내용에 대한 판정이 아닙니다. | 다시 시도하세요. |
| 502 | upstream_error | 회선이 답변 대신 오류 문장을 돌려주었습니다. | 다시 시도하세요. |
| 400 | content_filter | 모델이 요청을 처리했지만 아무 내용도 돌려주지 않았습니다. 대개 내용이 모델 제공사의 안전 정책에 걸린 경우입니다. | 프롬프트를 고친 뒤 다시 시도하세요. 같은 프롬프트는 대개 다시 거부됩니다. |
| 502 | upstream_prompt_filter | 모델 제공사의 사전 검사에서 프롬프트가 차단되었습니다. 모델이 내용을 판정한 것은 아닙니다. | 잠시 후 다시 시도하거나, 표현을 조금 바꿔 보세요. |
| 4xx | — | 모델 제공사가 요청을 거부했습니다(예: 컨텍스트가 너무 길거나 지원하지 않는 파라미터). 상태 코드와 message는 모델 제공사가 보낸 그대로 전달되며, code는 모델 제공사가 준 값입니다. | message에 적힌 대로 요청을 고치세요. |
Anthropic 엔드포인트
error.type은 상태 코드별로 Anthropic의 표준 값을 따릅니다: 400 invalid_request_error, 401 authentication_error, 402 billing_error, 403 permission_error, 404 not_found_error, 429 rate_limit_error(모든 회선이 가득 찼을 때는 overloaded_error), 502 api_error, 503 overloaded_error(모델 점검 중에는 api_error)./anthropic은 Claude 모델만 받습니다. 다른 모델을 지정하면 404 not_found_error가 돌아옵니다.max_tokens는 필수이며 0이면 안 됩니다. 그렇지 않으면 400이 돌아옵니다.
작업 실패(이미지와 영상)
이미지나 영상 작업이 접수된 뒤 실패해도 작업 조회 엔드포인트는 HTTP 200과 함께 status failed를 돌려줍니다. 사유는 error에 있고, error.code는 아래 값 중 하나입니다. 이 작업에 예약된 크레딧은 잔액으로 돌아옵니다. 웹훅을 쓰면 같은 내용의 image.failed / video.failed를 받습니다.
| code | 언제 나오나요 | 조치 |
|---|
content_policy | 영상: 프롬프트, 참조 소재, 또는 생성된 화면이나 소리가 콘텐츠 심사를 통과하지 못했습니다(소리가 걸렸으면 param이 audio입니다). | 프롬프트를 고쳐 쓰거나 참조 소재를 바꾼 뒤 다시 제출하세요. 같은 입력은 다시 거부됩니다. |
moderation_blocked | 이미지: 모델 제공사의 안전 시스템이 프롬프트나 참조 이미지를 거부했습니다(코드가 content_policy_violation일 수도 있습니다). | 프롬프트를 고쳐 쓰거나 참조 이미지를 바꾸세요. 그대로 다시 제출하면 대개 다시 거부됩니다. |
render_failed | 영상: 이번에는 영상이 나오지 않았습니다. 대개 일시적인 현상입니다. | 같은 요청을 그대로 다시 제출하면 대개 성공합니다. |
invalid_material | 영상: 업스트림이 입력 소재에 문제가 있다고 판단했습니다. 포괄적인 오류이며 일시적인 경우가 많습니다. | 먼저 그대로 다시 제출해 보세요. 계속 나오면 참조 소재와 프롬프트 길이를 확인하세요. |
render_timeout | 영상: 대기나 렌더링이 너무 오래 걸려 업스트림이 작업을 포기했습니다. | 다시 제출하세요. |
wait_timeout | 영상: 회선이 허용하는 최대 대기 시간 안에 영상이 나오지 않았습니다. | 다시 제출하세요. |
upstream_unstable | 영상: 렌더링 중에 연결이 끊겼습니다. | 다시 제출하세요. |
result_fetch_failed | 영상은 생성되었지만, 당사 측에서 영상을 내려받거나 저장하는 데 계속 실패했습니다. | 다시 제출하세요. |
invalid_request | 영상: 회선이 이 파라미터 조합(예: 길이, 비율, 해상도)을 받지 않습니다. | message에 적힌 대로 파라미터를 조정한 뒤 다시 제출하세요. |
upstream_error | 그 밖의 실패: 모든 회선을 시도했지만 실패했거나, 15분 동안 기다려도 시작되지 않았거나, 업스트림이 이유 없이 거부한 경우 등입니다. 구체적인 내용은 message에 있습니다. | 다시 제출하면 대개 성공합니다. |
비동기 작업 전체 안내 →
스트리밍 도중의 오류
- 스트리밍 요청이 HTTP 200으로 응답하고 출력을 시작한 뒤에는, 오류가 나도 상태 코드가 바뀌지 않습니다. 오류는
error가 담긴 데이터 이벤트로 오거나, 스트림이 그냥 끝납니다.
- 스트림이 끝까지 왔는지 확인하세요. OpenAI 형식은
finish_reason과 data: [DONE], Anthropic 형식은 message_stop을 받았는지 봅니다. 받지 못했다면 중간에 끊긴 것으로 처리하세요.
- 중간에 끊긴 스트림은 끊기기 전까지 생성된 사용량만큼 과금됩니다. 자세한 내용은 과금과 환불을 보세요.
오류가 나도 과금되나요?
- 오류를 돌려준 요청은 과금되지 않습니다. 과금 전에 오류가 나거나, 예약된 크레딧이 전액 돌아옵니다.
- 실패한 이미지·영상 작업은 전액 환불됩니다.
- 유일한 예외는 이미 출력을 시작한 스트리밍입니다. 중간에 끊기면 끊기기 전까지 생성된 사용량만큼 과금됩니다.
언제 재시도하나요
4xx는 먼저 요청을 고치세요(402는 충전, 429는 잠시 대기). 5xx 오류와 시간 초과는 그대로 재시도해도 되며, 지수 백오프로 간격을 두고 Retry-After가 있으면 그 시간만큼 기다리세요.
재시도 전략과 예제 코드 →
