跳转到主要内容

​
错误格式

大多数错误响应返回如下JSON对象： 
{
  "error": 401,
  "message": "invalid apiKey",
  "code": "invalid_api_key"
}
字段类型描述
error整数HTTP状态码
message字符串人类可读的描述
code字符串机器可读的原因代码

​
速率限制头

所有受速率限制器保护的端点返回以下头：
头描述
X-RateLimit-Limit每个窗口允许的请求数（每个apiKey）
X-RateLimit-Remaining当前窗口剩余的请求数
X-RateLimit-Reset窗口重置的Unix时间戳
如果达到限制（429），您还会收到：
头描述
Retry-After重试前等待的秒数

​
常见错误响应

​
400 — 错误请求

{
  "error": 400,
  "message": "Invalid filters.",
  "code": "invalid_filters"
}
用于语法有效但参数无效的请求。

​
401 — 未授权

缺少或无效的apiKey。 
{
  "error": 401,
  "message": "missing apiKey",
  "code": "missing_api_key"
}

{
  "error": 401,
  "message": "invalid apiKey",
  "code": "invalid_api_key"
}

​
403 — 禁止

有效的API密钥，但无权访问此频道或功能。 
{
  "error": 403,
  "message": "Access denied: apiKey is not allowed to access this endpoint.",
  "code": "channel_not_allowed"
}

​
422 — 验证错误

通常由FastAPI的内部验证返回。 
{
  "error": 422,
  "message": "Validation error",
  "code": "validation_error",
  "details": [
    {
      "loc": ["query", "fixtureId"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

​
429 — 超出速率限制

当请求量超过每个apiKey的限制时触发。 
{
  "error": 429,
  "message": "rate limit exceeded",
  "code": "rate_limited",
  "limit": 30,
  "windowSec": 1,
  "retryAfterSec": 1,
  "endpoint": "/fixtures/odds",
  "method": "GET"
}
头：
  • Retry-After: 1
  • X-RateLimit-Limit: 30
  • X-RateLimit-Remaining: 0
  • X-RateLimit-Reset: 1700000000

​
503 — 服务不可用

如果内部系统（如速率限制器）不可用： 
{
  "error": 503,
  "message": "rate limiter unavailable",
  "code": "rate_limiter_error"
}

​
说明

  • code是稳定的，适合程序化处理。
  • message可能会更改（但旨在帮助开发人员）。
  • 大多数端点在速率限制时返回429——请检查您的头。
  • FastAPI验证错误始终作为422返回。