오류 및 요청 한도

모든 엔드포인트는 기계 판독용 코드와 요청 ID를 포함한 동일한 구조로 실패를 보고합니다.

오류 응답

호출이 실패하면 success: false가 반환됩니다. code는 프로그램에서 쓰도록 고정된 값이고, error는 사람이 읽기 위한 짧은 영문 메시지이며, request_id는 당사 로그에서 해당 호출을 식별합니다. 입력값에 문제가 있을 때는 param에 문제가 된 파라미터 이름이 들어갑니다.

실제 예시

이 페이지를 렌더링할 때 API에서 가져온 실시간 응답입니다.

{
  "success": false,
  "error": "coin required",
  "code": "INVALID_PARAM",
  "request_id": "cb-mwefroqs-bac74b6fc2"
}

{
  "success": false,
  "code": "NOT_FOUND",
  "error": "unknown endpoint: GET /api/this-endpoint-does-not-exist",
  "request_id": "cb-mwefroqt-0f86946c0f"
}

오류 코드

요청 ID

모든 응답에는 X-Request-Id 헤더가 포함됩니다. 실패한 응답은 본문의 request_id에도 같은 값을 담습니다. 짧은 엣지 캐시에서 제공된 응답은 그 응답을 생성한 요청의 ID를 그대로 반환하므로, 연속 호출에서 ID가 같다면 캐시된 사본을 받았다는 뜻입니다.

요청 한도

한도는 분 단위로 적용되며, 익명 호출은 IP 주소별로, 유효한 CB-API-KEY 헤더를 보낸 경우에는 키별로 집계됩니다. 한도는 분당 1200회입니다. /api/coin-icon 아래의 아이콘 요청은 집계하지 않습니다.

요청 한도 헤더

한도를 초과한 경우

API는 HTTP 429와 코드 RATE_LIMITED로 응답합니다. Retry-After에 지정된 초만큼 기다린 뒤 다시 시도하십시오. 엔드포인트의 캐시 TTL보다 빠르게 폴링하면 캐시된 동일 응답이 반환되므로, 폴링 간격을 각 레퍼런스 페이지에 표시된 TTL에 맞추십시오.

백오프를 적용한 재시도

async function getJson(url, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url);
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get("Retry-After")) || 2 ** i;
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const body = await res.json();
    if (body.success === false) {
      throw new Error(body.code + ": " + body.error + " (" + body.request_id + ")");
    }
    return body;
  }
  throw new Error("gave up after " + tries + " attempts");
}

데이터 없음은 오류가 아닙니다

파라미터는 유효하지만 해당 데이터의 합법적인 공개 소스가 없는 경우 호출은 HTTP 200으로 성공합니다. 값 필드는 null, meta.quality는 UNAVAILABLE이며 coverage.unavailable에 사유가 나열됩니다. 대시로 표시하고 0으로 변환하지 마십시오.

만료된 데이터

수집기가 뒤처지면 엔드포인트는 마지막으로 저장된 값을 meta.is_stale: true와 함께 계속 제공합니다. 사용 가능 창을 지나면 이 값들은 집계에서 제외되고 coverage.stale_excluded에 나열됩니다.