# 오류와 재시도

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

문서: https://sendwich.kr/docs/api/errors/

## 오류 형식

```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 사용량](https://sendwich.kr/docs/usage/)에 포함됩니다.

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