오류 처리와 재시도

실패 응답은 success: false, data: null, 구조화된 error를 사용합니다.

필드	용도
code	안정적인 프로그램 분기
action	권장 조치 범주
request_id	서버 로그 추적과 지원 문의
message	사람이 읽는 설명
details	선택적인 구조화 정보

지역화될 수 있는 message로 분기하거나 모든 details 필드가 항상 있다고 가정하지 않습니다.

RATE_LIMITED, SERVICE_UNAVAILABLE 또는 action: RETRY_LATER인 읽기 요청만 제한된 지수 backoff로 재시도합니다. 매 시도마다 timestamp, nonce, signature를 새로 만듭니다.

생성 요청은 먼저 client_request_id 같은 업무 식별자로 결과를 복구합니다. 인증·검증·권한·잔액·충돌 오류는 반복 호출이 아니라 원인 수정이 필요합니다.

지원 문의에는 시각, 경로, HTTP 상태, code, action, request_id를 포함하되 API/HMAC Key는 포함하지 않습니다.

조치 결정표

Action	자동 처리
CORRECT_FIELD_VALUE, PROVIDE_REQUIRED_FIELDS	검증 실패와 수정 가능한 입력 정보 반환
SYNC_SYSTEM_TIME, GENERATE_NEW_NONCE, REGENERATE_SIGNATURE	한 번 수정하고 반복되면 중단
CHECK_RESOURCE_ID, REQUEST_ACCESS	환경·소유권·권한 확인
ADJUST_AMOUNT, INCREASE_BALANCE	새로운 업무 판단 요구
RESOLVE_CONFLICT	현재 상태를 조회하고 의도와 대사
RETRY_LATER	허용된 읽기만 jitter가 있는 제한 backoff로 재시도
CONTACT_SUPPORT	자동 처리 중단 후 진단 정보 보존

알 수 없는 action이나 잘못된 오류 envelope는 안전하게 실패 처리하고 민감하지 않은 원본 metadata를 보존합니다.