오류 및 재시도

오류는 안정적이고 기계가 읽을 수 있는 error 코드와 일치하는 HTTP 상태를 가진 JSON으로 반환됩니다.

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

오류 코드

HTTP	`error`	재시도?	비고
400	`invalid_request`	아니요	파라미터가 검증에 실패했습니다 — 요청을 수정하세요.
401	`missing_api_key` / `unknown_api_key`	아니요	인증을 참조하세요.
403	`inactive_api_key` / `account_blocked`	아니요	키가 비활성화되었거나 계정이 정지되었습니다.
402	`insufficient_credits`	아니요	충전하세요. 본문에는 `required`와 `balance`가 포함됩니다.
429	`rate_limited`	예, `retry_after_ms` 후	분당 한도를 초과했습니다.
409	`request_in_progress`	예	동일한 멱등 요청이 아직 실행 중입니다.
422	(멱등성 충돌)	아니요	`Idempotency-Key`가 다른 본문으로 재사용되었습니다.
503	`service_temporarily_unavailable` / `too_many_concurrent_requests`	예, 백오프 적용	일시적인 용량 제한.
504	`result_timeout`	예	업스트림 가져오기가 `deadline_ms`를 초과했습니다.

429 / 503 / 504 / 409는 지수 백오프로 재시도하세요. retry_after_ms가 있는 경우, 재시도 전에 최소한 그만큼 기다리세요.
400 / 401 / 402 / 403은 절대 재시도하지 마세요 — 변경하기 전까지는 요청이 성공하지 않습니다.
공식 SDK는 이미 일시적인 오류를 자동으로 재시도하며(기본 2회), 오류에 retryable 플래그를 노출합니다.