错误与状态码

finlight API 使用常规的 HTTP 状态码来表示请求的结果。2xx 状态表示成功；4xx 表示请求被拒绝（通常是您可以修复的问题）；5xx 表示我们这边出现了问题。每个错误都会返回一个描述出错原因的 JSON 正文。

注意： REST 和 WebSocket 请求使用 X-API-KEY 标头进行认证。缺失或无效的密钥会返回 401。（Webhook 投递认证 —— finlight 发送到您的端点的标头 —— 是独立的；参见 Webhook 认证。）

状态码一览

400 — Bad Request

当查询参数或请求正文未通过验证，或 query 字符串使用了无效的字段级语法时返回。

无效参数：

{
  "statusCode": 400,
  "message": ["pageSize must not be greater than 100"],
  "error": "Bad Request"
}

无效的 query 语法（POST /v2/articles）：

{
  "statusCode": 400,
  "message": [
    {
      "property": "query",
      "constraints": { "query": "Invalid query syntax near 'ticker:'" }
    }
  ],
  "error": "Bad Request"
}

有关正确的 query 语法，请参见高级查询构建。

401 — Unauthorized

X-API-KEY 标头缺失、格式错误，或不是有效的密钥。

{
  "statusCode": 401,
  "message": "Unauthorized"
}

在 finlight 控制台中获取或轮换您的密钥。

403 — Forbidden

请求已通过认证，但您的套餐不包含所请求的功能 —— 例如，在不包含完整文章内容的套餐上请求该内容。

{
  "statusCode": 403,
  "message": "Your subscription does not allow calling the extended article content"
}

有关每个套餐包含哪些功能，请参见速率限制与配额。

404 — Not Found

请求的资源不存在 —— 最常见的是 GET /v2/articles/by-link 使用了 finlight 尚未索引的 link。

{
  "statusCode": 404,
  "message": "Article not found"
}

422 — Unprocessable Entity

某些端点通过全局验证器进行验证，它会返回一个以字段为键的错误映射。每个键是出错的字段；其值列出了失败的约束。

{
  "status": 422,
  "errors": {
    "language": "language must be a string"
  }
}

注意： 验证失败可能表现为 400（在文章端点上）或 422（全局验证器），具体取决于路由 —— 两者都表示请求格式错误。请检查正文以查看是哪个字段失败。

429 — Too Many Requests

您已超出某项使用限制。有两种不同的情况，每种都有特定的消息：

超出每月请求配额：

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded token limit of 5000 for the current period."
}

超出突发（短期）速率：

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded rate limit of 10 requests per 10 seconds."
}

注意： finlight 目前不返回 Retry-After 或速率限制标头。对于突发 429，请回退并在约 10 秒后重试。对于每月配额 429，请求将在您下一个计费周期开始时（或升级后）再次成功。参见速率限制与配额。

500 — Internal Server Error

finlight 这边发生了意外错误。这类错误是暂时性的 —— 请带退避地重试；如果持续出现，请通过支持与我们联系。

{
  "statusCode": 500,
  "message": "Internal server error"
}

妥善处理错误

• 始终先检查状态码，然后阅读 JSON 正文以获取具体信息。
• 4xx（429 除外）是您的问题 —— 请修复请求；不做更改地重试无济于事。
• 429 和 5xx 可重试 —— 请使用指数退避。对于突发 429，约 10 秒即可。
• WebSocket 错误以套接字上的 error 服务器消息形式到达，而不是 HTTP 状态 —— 参见 WebSocket 基础。
• Webhook 投递失败（到您的端点）会在控制台中跟踪，而不是同步返回给您 —— 参见测试 Webhook。