API 오류와 그 의미
Didit API가 반환하는 각 HTTP 상태가 실제로 의미하는 바 - 키와 권한 문제인 401과 403, 402 계열의 잔액 문제, 429 속도 제한, 오류 본문을 읽는 방법.
응답 본문을 먼저 읽으세요. Didit의 오류에는 메시지와, 실제 문제를 알려주는 상세 코드가 함께 담기는 경우가 많습니다. 상태 코드만으로는 알 수 없는 경우가 대부분입니다. 401은 키 문제, 403은 권한이나 환경 문제, 429는 속도 제한이고, 잔액 오류는 코드가 아니라 크레딧 문제입니다.
#본문부터 확인하세요
HTTP 상태는 문제의 범주를 알려줍니다. 본문은 실제로 무슨 일이 일어났는지 알려줍니다. API 통합 과정에서 피할 수 있었던 디버깅 시간의 대부분은, 정작 답이 담겨 있던 응답을 무시한 채 상태 코드만 붙잡고 추측하는 데 쓰입니다.
- 비활성화되었거나 잘못된 애플리케이션의 키가 401의 주된 원인입니다.
- Last used를 보면 보내고 있다고 생각하는 키가 실제로 도착하는 키인지 확인할 수 있습니다.
- 키가 유출되었을 가능성이 있다면 시크릿을 교체하세요 - 401이 유출보다는 낫습니다.
실패한 모든 호출에 대해, 모든 환경에서 전체 오류 본문 - 상태, 헤더, 페이로드 - 을 로그로 남기세요. 나중에 다시 재구성하기는 훨씬 어렵고, 결국 필요해집니다.
#각 상태가 보통 의미하는 것
| 상태 | 일반적인 원인 |
|---|---|
| 400 | 잘못된 형식의 요청 - 필수 필드 누락, 잘못된 enum 값, 형식이 맞지 않는 중첩 객체 |
| 401 | 인증 실패. x-api-key 헤더가 없거나, 형식이 잘못되었거나, 유효한 키가 아님 |
| 403 | 인증은 되었지만 허용되지 않음. 잘못된 환경, 키에 없는 권한, 또는 계정에서 활성화되지 않은 기능 |
| 404 | 리소스가 존재하지 않음 - 또는 사용한 키와 다른 애플리케이션 아래에 존재함 |
| 409 | 기존 상태와의 충돌 - 예를 들어 이미 처리된 작업 |
| 422 | 요청 형식은 올바르지만 값이 허용되지 않음 - 문법 오류가 아니라 검증 실패 |
| 429 | 속도 제한. 아래 참고 |
| 5xx | Didit 쪽 문제. 백오프와 함께 재시도하고 status.didit.me를 확인하세요 |
#401 대 403 - 시간을 아껴주는 구분법
401은 키 자체가 전혀 받아들여지지 않았다는 뜻입니다. x-api-key를 보내고 있는지, 값에 불필요한 공백이나 따옴표가 없는지, API 키 대신 웹훅 서명 시크릿을 붙여넣지는 않았는지 확인하세요 - 둘은 전혀 다른 값이며 이 실수는 흔합니다.
403은 키는 유효하지만 이 호출이 허용되지 않는다는 뜻입니다. 원인은 다음 순서로 확인하세요.
- 환경 불일치.
sandbox_scenario처럼 샌드박스 전용 필드는 라이브 애플리케이션에서 거부되며, 반대의 경우도 마찬가지입니다. 라이브와 샌드박스는 각각 별도의 키를 가진 별개의 애플리케이션입니다. - 권한 누락. 일부 작업은 키나 역할이 보유하지 않은 권한을 필요로 합니다. 세션 생성 및 관리 권한이 필요한데 없다면, 이는 코드 수정이 아니라 지원팀에 요청할 사항입니다.
- 기능 미활성화. 일부 기능은 조직 단위로 제공됩니다. 당연히 있어야 한다고 생각하는 기능에서 403이 발생한다면, 코드를 다시 작성하기 전에 문의해 볼 가치가 있습니다.
겉으로 봐서는 샌드박스 키와 라이브 키를 구분할 방법이 없으므로, 시크릿 매니저에 분명히 구분되는 이름으로 저장하고 "현재 사용 중인 키"를 담는 단일 환경 변수를 두지 마세요. 테스트 환경에 라이브 키가 들어가면 실제 크레딧이 소모됩니다.
#존재해야 할 리소스가 404로 나오는 경우
세션이나 워크플로우가 404가 되었는데 분명히 존재한다고 확신한다면, 대개 인증에 사용한 키와 다른 애플리케이션 아래에 존재하는 경우입니다. 리소스는 애플리케이션 단위로 범위가 지정되므로, 애플리케이션 A의 키로는 애플리케이션 B의 세션을 볼 수 없습니다.
#잔액 및 크레딧 오류
크레딧이 부족해서 실패하는 호출은 코드 문제가 아닙니다. 워크플로우에 유료 기능이 포함되어 있고 잔액이 이를 감당하지 못하는 것입니다. "API가 고장났다"는 보고 중 가장 흔한 원인이며, 그 원인은 거의 항상 무료라고 예상했던 워크플로우에 화이트 라벨, AML, 또는 NFC가 포함된 경우입니다. 크레딧 부족 오류 해결하기를 참고하세요.
#429 속도 제한
제한은 식별자 단위로 적용됩니다 - x-api-key, 또는 키가 없다면 클라이언트 IP - 각 범위마다 60초 슬라이딩 윈도우로 독립적인 카운터가 적용됩니다.
전역 기본값:
| 범위 | 메서드 | 제한 |
|---|---|---|
| 일반 읽기 | GET | 분당 600회 |
| 일반 쓰기 | POST, PATCH, DELETE | 분당 300회 |
영향이 큰 일부 엔드포인트는 전역 제한에 더해 더 엄격한 제한이 있으며, 카운터를 먼저 초과하는 범위가 429를 반환합니다. 전체 표: 속도 제한.
429는 지수 백오프와 지터를 사용해 처리하세요. 속도 제한에 맞서 촘촘하게 재시도하면 문제가 더 악화되고, 제한이 무기한 풀리지 않을 수 있습니다.
429의 흔한 원인은 배치 작업입니다 - 야간 임포트가 몇 초 사이에 수백 건의 생성 요청을 쏟아내는 경우입니다. 오류가 멈출 때까지 동시성을 높이기보다는 작업을 분산시키세요.
#기능별 상세 코드
HTTP 상태 외에도, 개별 검사는 프로바이더 수준의 문제에 대해 자체 상세 코드를 반환합니다 - 예를 들어 특정 국가의 특정 상품에 접근 권한이 없는 레지스트리 연동 등입니다. 이런 코드를 받으면 상황을 정확히 지칭하고 있으므로, 문의할 때 그대로 인용하세요.
카탈로그에서 기대했던 상세 코드가 응답에 없다면, 우회하기보다는 보고할 가치가 있습니다 - 코드 누락은 실제 결함이며, 다음 사람에게는 같은 문제를 더 어렵게 만듭니다.
#빈 응답은 성공이 아닙니다
프로바이더 기반 검사가 빈 본문을 반환하는 것은 깨끗한 결과와 같지 않습니다. "데이터 없음"을 통과로 매핑하지 말고 코드에서 별도의 케이스로 처리하세요 - 특히 데이터베이스 검증과 지갑 스크리닝에서는, 서비스가 프로비저닝되지 않은 경우와 실제 불일치가 겉보기에 비슷해 보일 수 있습니다.
#오류 경로 테스트하기
샌드박스는 특정 실패를 결정적으로 강제할 수 있으며, 이것이 오류 처리를 테스트하는 유일하게 합리적인 방법입니다. 샌드박스에서 테스트하기를 참고하세요.