错误处理

TCG Price Lookup API的HTTP状态码、错误响应格式及处理方式。

错误响应格式

所有错误均返回一致的JSON格式：

{
  "error": {
    "code": "error_code",
    "message": "人类可读的错误描述",
    "details": {}
  }
}

HTTP状态码

状态码	说明
`200`	成功
`400`	请求错误（参数无效）
`401`	未认证（API密钥无效或缺失）
`403`	禁止访问（计划功能限制）
`404`	未找到（卡牌或资源不存在）
`429`	请求过多（超出请求限制）
`500`	服务器错误

常见错误及处理方式

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) {
    // 请求限制：查看重试等待时间
    const retryAfter = error.headers['retry-after'];
    console.log(`已达请求限制。请在${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"已达请求限制。请在{e.retry_after}秒后重试")
except AuthError:
    print("API密钥无效")