오류 처리

모든 실패는 한 가지 구조입니다.

실패 시 HTTP 상태 코드는 2xx가 아니며, 본문에는 error 객체 하나만 담깁니다:

json

{
  "error": {
    "message": "Insufficient credits: this request needs 60 credits. Top up and try again.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_credits"
  }
}

항목

항목	설명
message	사람이 읽는 영어 설명. 문구는 바뀔 수 있으니 분기 조건으로 쓰지 말 것
type	오류 대분류. 아래 표 참고
code	구체적 원인. 분기는 이 항목으로
param	문제가 된 파라미터 이름. 특정할 수 없으면 null

자주 만나는 오류

HTTP	code	의미와 처리
401	missing_api_key	Authorization 헤더가 없거나 Bearer sk-xxx 형식이 아님
401	invalid_api_key	없는 키·중지된 키·삭제된 키. 세 경우를 의도적으로 구분하지 않음
400	invalid_request	파라미터 문제. message 확인. prompt 가 비었거나 image 모드에 이미지가 없는 등
402	insufficient_credits	크레딧 부족. 충전 후 재시도하되 먼저 /v1/credits 확인 권장
429	rate_limit_exceeded	호출이 너무 잦음. 백오프 후 재시도
429	concurrency_limit_reached	동시 실행 또는 일일 한도 도달. 잠시 후 재시도
404	not_found	작업이 없거나 현재 키의 계정 소유가 아님
502	generation_failed	동기 생성에서 모든 이미지가 실패. 크레딧은 이미 환원됨
504	generation_timeout	동기 생성 대기 시간 초과. 작업은 계속 돌고 크레딧도 환원되지 않으니 메시지의 id로 /v1/tasks/{id} 에서 받아올 것
500	internal_error	서버 오류. 재시도 가능하며 계속되면 문의 바람

비동기로 접수된 뒤 생성이 실패한 경우는 이 구조가 아닙니다. 그때는 HTTP 200이고, 작업 객체의 status 가 failed 이며 원인은 error 에 담깁니다. 실패가 502로 오는 것은 동기 이미지 생성뿐입니다.