오류와 재시도

HTTP 상태별 오류 코드와 재시도 조건

오류 형식#

json

{
  "error": {
    "code": "idempotency_conflict",
    "message": "...",
    "request_id": "REQUEST_ID"
  }
}

HTTP 상태와 error.code로 오류를 구분합니다. 입력 검증 오류에는 fields가 추가될 수 있습니다. 문의 시 X-Request-ID 또는 error.request_id를 전달하면 요청을 식별할 수 있습니다.

HTTP	코드	조치
400	`invalid_idempotency_key`	허용된 문자로 8~128자의 키 생성
401	`authentication_required`, `invalid_api_key`	Bearer 헤더와 API 키 확인
403	`insufficient_scope`, `key_revoked`	키 권한 확인 또는 새 키 발급
403	`project_inactive`, `email_unverified`	프로젝트 상태·이메일 인증 확인
404	`not_found`	인증 ID, 소속 프로젝트, 보존 기간 확인
409	`idempotency_conflict`	기존 본문으로 재시도하거나 새 시도에 새 키 사용
422	`invalid_request`, `invalid_url`, `invalid_origin`, `invalid_return_url`	요청 필드와 프로젝트의 URL 등록값 확인
429	`monthly_call_limit`	다음 월 집계 시작 또는 요금제 변경 후 재개
503	`service_unavailable`, `sms_reader_unavailable`	대기 시간을 늘려 재시도
503	`live_not_enabled`, `destination_unconfigured`	서비스 연결 상태 문의
503	`code_unavailable`	재시도 후 반복되면 코드 형식·길이 변경

타임아웃이 발생해도 서버에서 인증이 생성되었을 수 있습니다. 생성 결과가 불확실하면 기존 Idempotency-Key와 본문을 유지해 재시도합니다. 실패가 반복되면 대기 시간을 늘리고 최대 횟수를 제한합니다.

429 monthly_call_limit은 월 허용량을 소진한 상태입니다. 짧은 간격으로 재시도해도 복구되지 않습니다. 실패한 요청과 재시도도 API 사용량에 포함됩니다.

조회 오류는 인증 결과가 아직 확인되지 않은 상태로 처리합니다. 이후 조회 또는 웹훅으로 최종 상태를 확인합니다.