오류 종류에 따라 다음 행동이 달라집니다
인증·입력
- 오류 응답인증값 또는 입력 형식 문제
- 요청 수정같은 잘못된 요청 반복 금지
충돌
- 내용 불일치키와 원본 본문 비교
- 상태 확인실제 처리 내용 대조
일시 장애·한도
- 일시 실패 또는 제한대기 조건 확인
- 제한된 재시도시간·횟수 상한 유지
시간 초과
- 응답 없음실패를 확정할 수 없음
- 원본 유지·결과 확인새 거래 생성 금지
분기마다 수정, 대기, 상태 확인의 행동이 다릅니다. 시간 초과와 명확한 입력 오류를 같은 방식으로 처리하지 않습니다.
오류 원인에 따라 행동하기
401·403은 인증 정보와 권한을, 입력 검증 오류는 필드와 값을 먼저 확인합니다. 409는 기존 요청과의 충돌 여부를 점검합니다. 같은 요청을 빠르게 반복해도 잘못된 키나 본문이 수정되지는 않습니다. 세부 오류 코드는 오류 문서를 기준으로 처리합니다.
일시 장애의 재시도
429나 일시적인 서버 오류에는 재시도를 검토할 수 있습니다. Retry-After가 제공되면 이를 존중하고, 간격을 늘리면서 임의 지연을 섞어 여러 호출이 한꺼번에 몰리지 않게 합니다. 최대 횟수와 전체 제한 시간을 정하고 초과한 요청은 별도로 추적합니다.
시간 초과 사례
10초 동안 응답이 없더라도 서버 처리 여부는 알 수 없습니다. 새 이벤트로 보내지 말고 저장한 요청과 멱등 키를 유지합니다. 지원되는 조회 API에서 현재 상태를 확인할 수 있으면 함께 사용합니다.
로그에 남길 것
요청 식별자, 발생 시각, 상태 코드, 안전한 오류 코드와 재시도 횟수를 기록합니다. API 키, 인증 쿠키, 전체 카드 정보는 기록하지 않습니다. 반복 장애는 요청 데이터 문제인지 연결 장애인지 구분한 뒤 담당자에게 전달하세요. 브라우저의 502 메시지만으로 원인을 특정하지 말고 서버와 프록시 로그를 대조해야 합니다.
가상 검증 사례
가상으로 잘못된 API 키에 401이 돌아왔다면 재시도 횟수를 늘리는 대신 키와 사이트 코드부터 고칩니다. 응답 없는 시간 초과는 다른 경우이므로 원본 키를 유지하고 상태 조회 가능 여부를 확인합니다.
이 사례는 실측 성능이나 실제 고객 자료가 아닙니다. 제품의 적용 범위는 GUARDIAN 공개 API 계약를 기준으로 확인합니다.
주장과 근거
- 인증·입력·충돌 오류는 요청을 수정하기 전에 반복 호출해도 해결되지 않습니다. 시간 초과는 처리 실패를 확정하지 못하므로 원본 본문과 키를 유지하고, 일시 장애에는 횟수와 시간을 제한한 재시도를 적용합니다. [GUARDIAN 공개 API 계약]
- 가상으로 잘못된 API 키에 401이 돌아왔다면 재시도 횟수를 늘리는 대신 키와 사이트 코드부터 고칩니다. 응답 없는 시간 초과는 다른 경우이므로 원본 키를 유지하고 상태 조회 가능 여부를 확인합니다. (가상 예시) [이 문서의 가상 검증 사례]
출처 목록
- GUARDIAN 공개 API 계약 · GUARDIAN FDS · 확인
- 이 문서의 가상 검증 사례 · GUARDIAN FDS · 설명용 사례 · 확인