錯誤與配額

按 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 時間、status、code 和 request_id 到 Narwhal API 支援。切勿提供 API 金鑰。

返回快速入門或查看經濟數據 API 參考。