에러 처리

TCG Price Lookup API의 HTTP 상태 코드, 에러 응답 형식 및 처리 방법.

에러 응답 형식

모든 에러는 일관된 JSON 형식을 반환합니다:

{
  "error": {
    "code": "error_code",
    "message": "사람이 읽을 수 있는 에러 설명",
    "details": {}
  }
}

HTTP 상태 코드

일반적인 에러 및 처리 방법

401 Unauthorized

{ "error": { "code": "unauthorized", "message": "Invalid or missing API key" } }

처리: API 키를 확인하세요. X-API-Key 헤더가 올바르게 설정되어 있는지 확인하세요.

429 Too Many Requests

{ "error": { "code": "rate_limit_exceeded", "message": "Daily limit reached" } }

응답에는 Retry-After 헤더가 포함되어 다음 요청까지의 초 단위 대기 시간을 나타냅니다:

Retry-After: 3600
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200

처리: Retry-After 헤더를 준수하세요. 일일 제한은 UTC 자정에 초기화됩니다. 더 많은 요청이 필요하면 플랜을 업그레이드하세요.

403 Forbidden

{ "error": { "code": "feature_not_available", "message": "Price history requires Trader plan" } }

처리: 가격 이력, 등급 가격, 일괄 검색 같은 기능에는 상위 플랜이 필요합니다.

SDK에서의 에러 처리

// JavaScript
try {
  const card = await tcg.cards.get('pokemon-base1-4');
} catch (error) {
  if (error.status === 429) {
    // Rate limit: 재시도 대기 시간 확인
    const retryAfter = error.headers['retry-after'];
    console.log(`Rate limit 초과. ${retryAfter}초 후에 재시도하세요`);
  } else if (error.status === 401) {
    console.error('API 키가 유효하지 않습니다');
  }
}

# Python
from tcglookup import TCGLookup, RateLimitError, AuthError

try:
    results = tcg.cards.search(name="charizard", game="pokemon")
except RateLimitError as e:
    print(f"Rate limit 초과. {e.retry_after}초 후에 재시도하세요")
except AuthError:
    print("API 키가 유효하지 않습니다")