오류
오류는 4xx 또는 5xx 상태의 JSON으로 반환됩니다. 형식은 엔드포인트의 프로토콜을 따르므로 OpenAI 및 Anthropic SDK는 평소와 같은 예외 클래스를 발생시킵니다. 한 가지 다른 경우가 있습니다. 비스트리밍 요청이 90초 동안 실행된 뒤 발생한 오류는 200 응답 본문에 담겨 전달됩니다(긴 요청 참고).
오류 코드
| 코드 | 상태 | 발생 조건 |
|---|---|---|
invalid_api_key | 401 | API 키가 없거나, 형식이 잘못되었거나, 알 수 없거나, 폐기되었거나, 만료되었습니다. 만료된 키의 경우 메시지에 만료일이 표시됩니다. |
account_suspended | 403 | 계정이 정지되었습니다. 정지가 끝날 때까지 계정의 모든 키가 거부됩니다. 지원팀에 문의하세요. |
account_banned | 403 | 계정이 영구 정지되었습니다. 계정의 키는 폐기되며 남은 크레딧은 소멸됩니다. |
card_network_blocked | 403 | 카드 충전이 거부되었습니다. 요청이 VPN, Tor 또는 데이터센터 네트워크에서 왔습니다. |
card_account_risk | 403 | 카드 충전이 거부되었습니다. Stripe의 사기 방지 심사에서 계정이 가장 높은 위험 등급으로 평가되어 카드로 충전할 수 없습니다. 암호화폐 충전은 계속 이용할 수 있습니다. |
model_not_found | 404 | model ID가 활성화된 모델이 아닙니다. GET /v1/models에서 ID 목록을 확인하세요. |
unsupported_content | 400 | 요청에 모델이 받지 않는 부분이 포함되어 있습니다. input_modalities에 해당 유형이 없는 모델에 보낸 이미지 또는 동영상 부분, https:// URL이 아닌 동영상(base64 동영상 포함), https://, http://, data: 형식이 아닌 이미지 URL, 또는 어떤 모델도 받지 않는 오디오나 파일 부분이 이에 해당합니다. |
content_policy_violation | 400 | 자동 안전 검사에서 요청이 차단되었습니다. |
stateless_only | 400 | /v1/responses 요청에 previous_response_id 또는 background: true 값이 설정되었습니다. 대신 background 없이 전체 대화를 input에 담아 보내세요. |
invalid_request | 400 | 요청 본문이 유효성 검사를 통과하지 못했거나(예: /v1/messages에서 max_tokens 누락, 1이 아닌 n, /v1/completions의 prompt 배열에 프롬프트 4개 초과, 우선 처리 등급이 없는 모델에 service_tier: "priority" 지정, function 외의 도구 유형(/v1/responses에서는 custom, namespace도 허용), Completions 엔드포인트가 없는 모델로 /v1/completions 요청), 본문이 제시간에 도착하지 않았거나(상태 408) 16 MiB를 초과했거나(상태 413), 모델이 요청을 거부했습니다(예: 컨텍스트 윈도우보다 긴 프롬프트, 모델이 받을 수 있는 수보다 많은 이미지). 모델이 거부한 경우에는 모델이 반환한 4xx 상태와 메시지가 그대로 유지됩니다. |
insufficient_balance | 402 | 잔액으로 예상 입력 비용과 최소 256토큰 분량의 출력 예산을 충당할 수 없습니다. 크레딧을 충전하세요. |
key_spend_cap_reached | 402 | 이 요청의 임시 차감액을 키의 확정된 사용 금액 및 처리 중인 다른 요청과 합하면 키의 일일, 월간 또는 누적 지출 한도를 넘게 됩니다. |
rate_limit_exceeded | 429 | 키 또는 계정의 이번 1분간 요청이 너무 많거나, 계정의 동시 요청이 너무 많거나, 계정의 대용량 업로드가 처리 중 본문 예산을 너무 많이 차지하고 있거나, 체험 계정의 경우 1시간 안에 같은 네트워크에서 요청을 보낸 체험 계정이 2개를 넘었습니다. 분당 한도와 체험 네트워크 한도에는 Retry-After 헤더가 함께 전송됩니다. |
capacity_exhausted | 429 | 모델의 모든 레플리카가 30초간 재시도하는 동안 계속 사용 중이었거나(체험 계정은 재시도 없이 즉시 실패), 게이트웨이가 잠시 처리 용량에 도달했거나 재시작 중입니다(상태 503). Retry-After에 표시된 초만큼 기다리세요. 서빙 용량이 전혀 없는 모델은 대신 model_unavailable 오류를 반환합니다. 요금은 청구되지 않습니다. |
model_unavailable | 503 | 현재 모델에 서빙 용량이 없습니다(예: GPU 교체 중). 요청은 모든 계정에서 재시도 없이 즉시 실패합니다. Retry-After는 당사가 모델을 다시 확인하기까지 남은 초를 알려 줍니다. 그때 다시 시도하거나 다른 모델을 사용하세요. 요금은 청구되지 않습니다. |
safety_unavailable | 503 | 안전 검사가 시간 초과되었거나 실패해, 검사하지 않은 채로 보내는 대신 요청을 거부했습니다. 잠시 후 다시 시도하세요. |
card_network_check_unavailable | 503 | 네트워크 확인을 잠시 사용할 수 없어 카드 충전이 거부되었습니다. 다시 시도하거나 암호화폐로 결제하세요. |
upstream_error | 502 | 모델 백엔드가 실패했거나, 요청이 10분 시간 제한, 모델 출력 없이 2분 경과, 또는 재시작으로 중단되었습니다. 응답을 보내기 전이라면 예기치 않은 내부 오류는 상태 500, 당사 측의 일시적 장애나 재시작은 상태 503과 Retry-After, 백엔드 실패는 상태 502와 함께 이 코드를 반환합니다. 시간 제한은 그 이후에야 도달합니다. 시간 제한은 스트림을 종료하며, 90초 후에도 실행 중인 비스트리밍 응답은 이미 상태 200으로 전송된 상태이므로, 시간 제한이든 다른 원인이든 이 오류는 Retry-After 없이 응답 본문에 담겨 전달됩니다(“긴 요청” 참고). 모델이 아직 출력을 생성하지 않았다면 요금이 청구되지 않으니 요청을 다시 시도하세요. 출력을 생성한 후라면 예상 입력과 실패 또는 중단 전까지 생성된 출력에 대해 요금이 청구됩니다. 연결을 끊은 클라이언트는 이 오류를 받지 않으며, 출력이 생성되지 않았더라도 예상 입력에 대해 요금이 청구됩니다. |
content_policy_violation 오류로 차단되는 내용은 이용 정책에 정의되어 있습니다.
OpenAI 형식
/v1/chat/completions, /v1/responses, /v1/models, /v1/balance에서 사용합니다. code 값은 위 오류 코드 중 하나입니다. 예:
{
"error": {
"type": "rate_limit_error",
"code": "capacity_exhausted",
"message": "All model replicas are busy. Retry shortly."
}
}Anthropic 형식
/v1/messages에서 사용합니다. 이 형식에는 code 필드가 없으므로 HTTP 상태와 error.type 값을 확인하세요. 예:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens is required."
}
}상태별 오류 유형
| 상태 | OpenAI error.type | Anthropic error.type |
|---|---|---|
| 400 | invalid_request_error | invalid_request_error |
| 401 | authentication_error | authentication_error |
| 402 | insufficient_quota | billing_error |
| 403 | permission_error | permission_error |
| 404 | not_found_error | not_found_error |
| 408 | invalid_request_error | invalid_request_error |
| 413 | invalid_request_error | request_too_large |
| 429 | rate_limit_error | rate_limit_error |
| 500, 502, 503 | api_error | api_error |
헤더
x-request-id헤더는 오류를 포함한 모든 응답에 있습니다. 지원팀에 문의할 때 이 값을 알려 주세요.Retry-After(초 단위)는capacity_exhausted,model_unavailable(모델을 다시 확인할 때까지 남은 초, 최대 15), 분당 한도 및 체험 네트워크 한도의rate_limit_exceeded, 그리고 503upstream_error(당사 측의 일시적 장애 또는 재시작)와 함께 전송됩니다.
재시도 시점
| 오류 | 조치 |
|---|---|
capacity_exhausted | Retry-After에 표시된 초만큼 기다린 뒤 다시 시도하세요. 429는 유료 요청이 이미 최대 30초 동안 재시도되었다는 뜻이고, 503은 게이트웨이가 용량 한계에 도달했거나 재시작 중이어서 요청이 모델에 닿지 못했다는 뜻입니다. |
model_unavailable | Retry-After에 표시된 초만큼 기다린 뒤 다시 시도하세요. 그때 모델을 다시 확인합니다. 모델에 서빙 용량이 없어 요청이 재시도 없이 즉시 실패한 것입니다. 이런 장애는 몇 분간 이어질 수 있으므로 오류가 계속되면 다른 모델로 전환하세요. |
rate_limit_exceeded | 분당 한도라면 Retry-After에 표시된 초만큼 기다리세요. 동시 요청 한도라면 실행 중인 요청 중 하나가 끝났을 때 다시 시도하세요. 네트워크당 체험 계정 한도라면 Retry-After에 표시된 초만큼 기다리거나 충전하세요. 유료 계정에는 이 제한이 적용되지 않습니다. |
safety_unavailable | 몇 초 뒤 다시 시도하세요. 안전 검사는 실패 시 차단(fail-closed) 방식입니다. 검사를 실행할 수 없으면 검사 없이 전달하지 않고 요청을 거부합니다. |
upstream_error | 상태가 503이면 Retry-After에 표시된 초만큼 기다린 뒤 다시 시도하세요. 그 밖의 경우(200 본문으로 받은 경우 포함)에는 지수 백오프로 다시 시도하세요. |
insufficient_balance, key_spend_cap_reached | 충전하거나, 한도를 올리거나, 한도가 초기화될 때까지 기다리세요. 그 전에 다시 시도해도 소용없습니다. |
| 기타 4xx | 요청을 수정하세요. 그대로 다시 보내면 같은 오류가 반환됩니다. |
출력을 생성하지 않고 실패한 요청에는 비용이 청구되지 않습니다. 시간 제한이나 재시작으로 중단된 요청도 마찬가지입니다. 유일한 예외는 클라이언트의 연결 끊김으로, 출력이 생성되지 않았더라도 추정 입력에 대해 청구됩니다. 모델이 출력을 생성한 뒤 실패하거나 중단된 요청은 추정 입력과 종료 전까지 생성된 출력에 대해 청구됩니다. 요청 과금 방식을 참고하세요.
긴 요청
비스트리밍 응답은 모델이 생성을 마쳤을 때 완성되는 하나의 JSON 객체입니다. 요청이 도착한 지 90초 안에 준비되면 결과든 오류든 자체 상태와 헤더를 담아 평소처럼 전송됩니다.
90초가 지나도 준비되지 않은 응답은 연결이 유지되도록 그 시점에 전송을 시작합니다. 상태 200과 Content-Type: application/json(및 x-request-id)이 먼저 전송되고, 본문은 줄바꿈(\n)으로 시작해 15초마다 줄바꿈이 하나씩 추가됩니다. 결과가 준비되면 JSON 객체가 이어지고 응답이 끝납니다. JSON 파서는 값 앞의 공백을 건너뛰므로 OpenAI 및 Anthropic SDK, JSON.parse, json.loads, response.json() 모두 이 응답을 그대로 읽습니다. 이 방식으로 비스트리밍 요청에도 10분 시간 제한 전체가 주어집니다.
상태가 200으로 전송된 뒤에는 오류가 발생해도 상태를 바꿀 수 없습니다. 그 이후의 오류(10분 시간 제한, 모델의 출력 없이 2분 경과, 백엔드 장애, 재시작)는 일반적인 오류 객체로 200 본문에 담겨 전달됩니다. 형식은 OpenAI 형식이며, /v1/messages에서는 Anthropic 형식입니다. 이때는 Retry-After 헤더를 보낼 수 없습니다. 상태만 확인하는 클라이언트는 오류를 알아차리지 못하므로 본문에 최상위 error 멤버가 있는지 확인하세요. 과금은 다른 실패하거나 중단된 요청과 같으며(위 참고), 기다리는 동안 연결을 닫으면 클라이언트 연결 끊김으로 처리됩니다.
긴 생성 작업에는 여전히 "stream": true 스트리밍이 좋은 선택입니다. 첫 토큰을 일찍 볼 수 있고 출력이 생성되는 대로 확인할 수 있습니다. 다만 타임아웃을 피하려고 스트리밍을 쓸 필요는 없습니다.