오류와 재시도

오류 응답 읽기

{
  "error": {
    "code": "FIELD_REQUIRED",
    "message": "A required field is missing.",
    "request_id": "req_EXAMPLE_ONLY",
    "retryable": false,
    "field_errors": [
      {
        "field": "target",
        "code": "FIELD_REQUIRED",
        "message": "target is required."
      }
    ],
    "docs_url": "https://docs.example.com/errors/field-required"
  }
}

예제의 message는 설명용입니다. 프로그램 분기는 사람용 문장보다 error.code를 기준으로 하며, field_errors로 수정할 입력을 찾습니다.

안전한 재시도 순서

1. 실제 error.retryable을 확인합니다. false이면 입력·권한·최신 상태를 먼저 고치며 무조건 같은 요청을 반복하지 않습니다.
2. Retry-After가 있으면 최소 그 시간만큼 기다립니다. 짧은 간격의 무한 반복 대신 제한된 횟수와 점차 늘어나는 대기 시간을 사용합니다.
3. 같은 논리적 작업의 재시도에는 본문과 멱등성 키를 유지합니다. 타임아웃으로 결과를 모를 때 새 키로 보내면 중복 작업이 될 수 있습니다.
4. IDEMPOTENCY_KEY_REUSED는 다른 본문에 키를 재사용한 충돌입니다. 이전 작업의 결과와 현재 의도를 확인하세요. IDEMPOTENCY_IN_PROGRESS는 처리 중이므로 Retry-After 뒤 동일 요청을 확인합니다.
5. SDK의 Queued는 서버 성공이 아닙니다. SDK가 영속 재시도를 관리하므로 앱에서 별도의 무한 네트워크 루프를 만들지 마세요.

문의할 때

발생 시각·시간대, API 경로와 메서드, HTTP 상태, error.code, request_id, SDK 버전과 플랫폼을 전달하세요. 사용자 개인정보, 본문 전체, 비밀번호, API 키, 기기·푸시 토큰, 초대·재설정 링크는 보내지 마세요.