요청 제한 및 서버 오류 처리하기

429 응답 처리하기

요청 제한에 걸린 요청은 429 Too Many Requests로 응답하며 detail.status는 rate_limit_exceeded로 설정됩니다. 다시 시도하기 전에 응답 헤더를 확인하세요.

• Retry-After는 거부된 요청을 다시 보내기 전 기다려야 하는 최소 시간(초)입니다.
• X-RateLimit-Limit는 버킷의 요청 한도입니다.
• X-RateLimit-Remaining은 남은 요청 수입니다.
• X-RateLimit-Reset은 버킷이 초기화되는 시각입니다.

Retry-After만큼 기다린 다음 지수형 백오프와 지터를 적용해 다시 시도하세요. 창이 초기화되자마자 요청을 한꺼번에 보내지 말고 병렬 요청을 줄이고 작업을 큐에 넣으세요.

서버 오류 처리하기

500 응답의 공개 본문에는 일반 오류와 request_id가 포함되며 내부 예외 세부 정보는 반환되지 않습니다. 503은 필요한 서비스가 일시적으로 제공되지 않음을 뜻할 수 있습니다.

읽기 전용 요청은 횟수를 제한해 백오프를 적용한 뒤 다시 시도하세요. 생성, 업데이트, 결제 또는 상태를 바꾸는 요청을 다시 보내기 전에 첫 번째 시도가 완료되었는지 확인하세요. 시간 초과나 5xx 응답은 변경 작업이 실패했다는 증거가 아닙니다. 즉시 반복하면 작업이 중복될 수 있습니다.

진단 정보 보관하기

시각, 메서드, 경로, 상태, 응답 본문, X-Request-Id를 기록하세요. x-api-key 값은 로그에 남기지 마세요. 자동 재시도는 적은 횟수로 제한하고 실패를 검토할 수 있도록 표시하세요.