错误与配额

按 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"
}

状态与代码

状态	公开code	含义
`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 自然月额度。对于已认证的响应，短时窗口标头描述的免费账户限额为 30 每分钟请求数，突发容量为 5。独立的滥用防护限流桶允许每个网络身份每分钟请求 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 密钥。

返回该快速入门或查看 Economics API 参考.