오류와 재시도

오류 메시지 언어

사람이 읽는 오류 메시지는 호출하는 쪽이 고른 언어로 받을 수 있습니다. 대상은 응답의 msg, 실패한 작업의 errorMessage(recordInfo와 webhook 알림 모두), 호환 API 오류 객체의 error.message(OpenAI·Anthropic·Google Gemini 형식 모두 해당) 세 가지이며 기본값은 영어입니다. 지원하는 언어 코드는 en, zh-Hant, ja, ko, de, fr, es, pt-BR, ru입니다.

바뀌는 것은 사람이 읽는 문장뿐입니다. code와 errorCode, OpenAI 호환 계층의 type과 code, Gemini 호환 계층의 code와 status, 그리고 필드 이름은 언어와 관계없이 그대로입니다. 처리 분기는 반드시 코드로 하고 문구를 파싱하지 마세요. 로그와 알림에는 code와 request_id를 기록하는 것을 권장합니다. 실제로 적용된 언어는 응답 헤더 Content-Language로 확인할 수 있습니다. 예를 들어 같은 40201(잔액 부족)의 msg는 기본적으로 “Insufficient balance”이지만, Accept-Language: ja를 보내면 일본어로 바뀝니다. code는 그대로 40201입니다.

언어는 다음 우선순위로 정해집니다.

• Accept-Language 요청 헤더: 해당 요청에만 적용됩니다. 표준 HTTP 가중치에 따라 인식할 수 있는 언어 중 q 값이 가장 높은 언어를 고릅니다. de-DE는 de로, pt-PT는 pt-BR로, zh-TW·zh-HK·zh-Hant는 zh-Hant로 처리합니다. 중국어는 번체만 제공하므로 zh-CN과 zh-Hans는 어떤 언어와도 일치하지 않고 다음 후보로 넘어갑니다. *는 선호 언어가 없는 것으로 봅니다.
• 계정 설정: 콘솔의 ‘설정 → API 오류 언어’입니다. 이 계정의 API 키로 보낸 요청 가운데 인식할 수 있는 Accept-Language가 없는 요청에 적용됩니다. 서버용 SDK 대부분과 curl은 기본적으로 이 헤더를 보내지 않으므로 실제로는 이 방법을 가장 많이 씁니다. webhook 알림에는 요청 헤더가 없으므로 항상 계정 설정을 따릅니다.
• 둘 다 없으면 영어로 반환합니다.

# Default: no Accept-Language, no account setting
HTTP/1.1 402 Payment Required
Content-Language: en

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }

# The same request with one extra header
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "Accept-Language: ja" \
  --data "$TASK_PAYLOAD"

HTTP/1.1 402 Payment Required
Content-Language: ja

{ "code": 40201, "msg": "残高が不足しています", "request_id": "req_…" }

재시도하지 않을 오류

400, 401, 403, 404, 40201, 40202, 40301~40303은 입력, 자격 증명, 권한, 잔액이나 한도를 수정하지 않으면 해결되지 않습니다. 413은 본문이 너무 크다는 뜻이므로 그대로 재시도하지 말고 본문을 줄이거나 미디어 업로드 절차를 사용하세요.

재시도 가능한 오류

429는 Retry-After를 따릅니다. HTTP 500/503 또는 비즈니스 코드 500/50301은 지수 백오프와 지터로 재시도합니다. 409는 작업별로 판단합니다. 미디어 pending과 동일한 Idempotency-Key·동일한 payload에서 발생한 드문 createTask 동시성 충돌만 잠시 기다린 뒤 재시도하세요. 다른 payload에 사용한 키 충돌은 재시도하지 마세요.

작업 생성의 네트워크 재시도에는 같은 Idempotency-Key를 재사용하세요. 다른 payload에 같은 키를 쓰면 409가 발생합니다.

과금

작업 생성 전에 거부된 요청은 과금되지 않습니다. 생성 후 failed·expired와 과거 canceled 기록은 hold가 전액 해제됩니다. 새로 수락된 작업은 취소되지 않으며 succeeded만 실제 사용량으로 정산됩니다.