错误与配额

根据 HTTP 状态和稳定的机器可读错误代码处理 Narwhal 错误。

REST 错误使用 application/problem+json。MCP 工具错误的结构化内容包含相同的问题字段。

错误响应

分支依据 status 首先以及 code 进行后续判断。将 detail 作为便于人类阅读的诊断文本，而不是稳定的程序值。

RFC 9457 问题详情

{
  "ok": false,
  "type": "https://narwhalapi.com/problems/series-not-found",
  "title": "Economics series not found",
  "status": 404,
  "detail": "No approved economics observations matched the request.",
  "code": "series_not_found",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50",
  "instance": "/v1/economics/USA/cpi"
}

状态与代码

状态	公开错误代码	含义
`400`	`invalid_query`	国家、期间或其他请求输入无效。
`401`	`invalid_api_key`	Bearer 密钥缺失、格式错误、未知或未激活。
`404`	`series_not_found`	没有已批准的当前或历史观测值符合请求。
`404`	`route_not_found`	请求的REST路由不存在。
`404`	`tool_not_found`	请求的 MCP 工具不是公共工具，或不存在。
`405`	`method_not_allowed`	该路由存在，但不接受请求的HTTP方法。
`429`	`rate_limit_exceeded`	已达到网络或账户的短时窗口限额；请按以下响应头指定的等待时间重试： `Retry-After`。
`429`	`quota_exhausted`	该账户已用完月度请求配额。
`500`	`internal_error`	Narwhal 无法完成请求。
`503`	`api_disabled`	公共数据入口暂时关闭。
`503`	`economics_unavailable`	Narwhal 无法安全地根据已接受的官方发布满足请求。
`503`	`database_unavailable`	数据存储暂时不可用。
`503`	`rights_state_changing`	Narwhal 无法确认在准备响应期间，数据来源的使用许可是否始终未发生变化。

配额响应头

每次成功的数据响应恰好消耗一次配额，并包含：

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetX-RateLimit-Short-LimitX-RateLimit-Short-RemainingX-RateLimit-Short-Reset

常规响应头显示 3,000次请求的 UTC 自然月配额。对于通过身份验证的响应，短时窗口响应头显示 Free 账户的限额为每分钟 30 次请求。独立的滥用防护限流桶允许每个网络身份每分钟请求 120 次，突发容量为 20，因此共享同一地址的客户端可能一起受到限流。 429 rate_limit_exceeded 包括 Retry-After ，指示触发限流的短时窗口所需的等待时间； 429 quota_exhausted 则须等到下一个 UTC 自然月。两种响应均不消耗月度配额。

重试行为

不要重试以下请求： 400 （请求尚未更正时）。
不要重试以下请求： 401 （仍使用同一个被拒绝的密钥时）。
重试 429 只有在 Retry-After 或 X-RateLimit-Reset。
遇到以下状态码时重试幂等请求： 500 或 503 ，并采用设有上限的指数退避和随机抖动。
A 404 series_not_found 表示所请求的数据可能要等到受支持的官方数据版本发布后才可用。

寻求帮助

请将端点、UTC 时间、状态、代码以及 request_id 发送给 Narwhal API 支持团队。切勿提供 API 密钥。

返回快速入门或查看经济数据 API 参考。