錯誤與配額

按 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 參考.