Chat 등 주요 추론 API는 다음 OpenAI 호환 envelope을 사용합니다.
Messages는 일부 경로에서 Anthropic 형식(type: "error")을 반환하며, 스트림이 시작된 뒤의 오류는 SSE 본문으로 전달됩니다.
json
{
"error": {
"message": "Incorrect API key provided. ...",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}| 상태 | type / code | 의미 |
|---|---|---|
| 400 | invalid_request_error | 잘못된 파라미터 / 컨텍스트 초과 (재시도 금지) |
| 401 | authentication_error / missing_api_key · invalid_api_key | 키 누락·오류·만료 |
| 402 | insufficient_quota_error / insufficient_quota · spend_limit_exceeded | 크레딧 부족 또는 지출 한도 도달 |
| 403 | permission_error / model_not_allowed · insufficient_scope | 키의 허용 모델·스코프 제한 |
| 404 | invalid_request_error / model_not_found · job_not_found | 존재하지 않는 모델 또는 작업 |
| 413 | invalid_request_error | 요청 본문 초과 — 본문 크기 제한 참고 |
| 429 | rate_limit_error / rate_limit_exceeded | 레이트리밋 — Retry-After 헤더 후 재시도 |
| 502 | api_error / backend_unavailable | 업스트림 프로바이더 장애 (재시도 가능) |
레이트리밋
기본 레이트리밋은 키당 100 req/min 이며 키 생성·수정 시 조정할 수 있습니다.
응답의 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset 헤더로 잔여량을 확인하세요.
인증 엔드포인트(로그인·회원가입 등)에는 더 낮은 별도 한도가 적용됩니다.
재시도 기준
- 400·401·402·403은 입력, 인증, 크레딧 또는 접근 정책을 먼저 해결하세요.
- 429는
Retry-After의 초 단위 대기 시간 이후 재시도하세요.X-RateLimit-Reset은 Unix 밀리초입니다. - 502·503은 일시적 장애일 수 있습니다. 대기 시간을 늘려 재시도하되 중복 실행 여부를 먼저 확인하세요.
- 409
idempotency_in_progress는 같은 요청이 처리 중이라는 뜻입니다. 새 키로 재제출하지 말고 기다리세요. - 409
idempotency_key_reused는 같은 키로 다른 본문을 보낸 경우입니다. - 409
idempotency_response_not_replayable는 이미 접수된 스트림 또는 큰 응답을 재생할 수 없다는 뜻입니다.
x-request-id와 HTTP 상태, error.code를 기록하면 실패 요청을 추적하기 쉽습니다.
비디오 POST는 Idempotency-Key 대상이 아니므로 결과를 받지 못했다고 즉시 재제출하면 작업이 중복될 수 있습니다.
멱등성 범위와 비디오 폴링을 확인하세요.