시작하기

오류

오류 형식과 상태 코드, 재시도해야 하는 경우를 정리했어요.

오류는 일반적인 HTTP 상태 코드를 사용하며, 변하지 않는 기계 판독용 코드가 담긴 동일한 JSON 구조로 항상 반환돼요.

오류 형식#

{
  "error": {
    "code": "rateLimited",
    "message": "Rate limit exceeded",
    "retryAfter": 12
  }
}

error.code 값은 바뀌지 않으므로 분기 처리에 안심하고 쓸 수 있어요. error.message 값은 사람이 읽기 위한 안내 문구라서 바뀔 수 있어요. 일부 오류에는 필드가 추가돼요. 요청 한도 초과에는 retryAfter, 할당량 초과와 플랜 제한에는 reason, 유효성 검사 오류에는 issues 필드가 붙어요.

오류 코드#

상태	코드	의미	재시도 여부
400	validation	파라미터나 요청 본문이 유효하지 않아요. `error.issues` 값을 확인하세요.	아니요
401	unauthorized	API 키가 없거나, 형식이 잘못됐거나, 폐기됐어요.	아니요
402	planRequired	플랜에 API 접근 권한이나 이 기능이 포함되어 있지 않아요.	아니요
403	forbidden	허용되지 않는 요청이에요.	아니요
404	notFound	토큰이 아직 스캔되지 않았거나 지갑 프로필이 아직 없어요.	나중에
409	conflict	요청이 현재 상태와 충돌해요.	아니요
429	rateLimited	분당 요청이 너무 많거나 월간 할당량을 모두 사용했어요.	예
500	generic	XCA 서버에서 문제가 발생했어요.	예
503	unavailable	점검 중이거나 데이터 제공업체의 처리 용량이 부족해요.	나중에

유효성 검사 오류#

파라미터가 유효하지 않으면 400 오류와 함께, 문제가 있는 필드를 가리키는 issues 목록이 반환돼요.

400

{
  "error": {
    "code": "validation",
    "message": "Invalid input",
    "issues": [
      {
        "path": "pageSize",
        "message": "Invalid input"
      }
    ]
  }
}