エラーとクォータ

HTTP ステータスと安定した機械可読コードを使って Narwhal のエラーを処理します。

REST エラーのメディアタイプは application/problem+jsonです。MCP ツールのエラーも、構造化コンテンツ内に同じエラー情報のフィールドを持ちます。

エラーレスポンス

条件分岐ではまず status を確認し、次に code を確認してください。 detail は、人が読んで原因を調べるためのテキストとして扱い、プログラムで使う安定した値としては扱わないでください。

RFC 9457 問題

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

ステータスとコード

ステータス	公開コード	意味
`400`	`invalid_query`	国、期間、その他のリクエスト入力が無効です。
`400`	`invalid_cursor`	ページネーションのカーソルの形式が不正か、異なるフィルターに属しています。
`400`	`invalid_pair`	fromとtoの通貨が同じです。
`401`	`invalid_api_key`	Bearer キーがない、形式不正、未知、または無効です。
`403`	`plan_upgrade_required`	指定した履歴がプランの期間を超えています。Freeは12か月、Basicは5年です。このコードは、有料の市場機能や、プランで許可される時点より新しい予測データにも使います。
`404`	`series_not_found`	リクエストに一致する承認済みの最新または過去の観測値はありません。
`404`	`resource_not_found`	コマンドで指定したリソースは利用できません。
`404`	`event_not_found`	ID に一致するイベントがありません。
`404`	`not_found`	ID に一致する発表がカレンダーにありません。
`404`	`route_not_found`	指定された REST ルートは存在しません。
`404`	`tool_not_found`	指定された MCP ツールは公開されていないか、存在しません。
`404`	`calendar_not_published`	指定された国と年のカレンダーは公開されていません。
`404`	`commodity_not_supported`	この商品コードのスポット価格およびバーは提供していません。
`404`	`currency_not_supported`	この商品は指定した通貨では建値されていません。
`404`	`subscription_not_found`	カレンダーの購読IDが未知か、自分のものではありません。
`404`	`physical_series_not_found`	IDに一致する現物価格系列がありません。
`404`	`palmoil_series_not_found`	IDに一致するパーム油系列がありません。
`404`	`webhook_request_failed`	Webhookの送信先が未知か、その配信を再配信できません。
`405`	`method_not_allowed`	ルートは存在しますが、指定された HTTP メソッドを受け付けません。
`409`	`cursor_expired`	カーソルの期限が切れたか、スナップショットが利用できません。カレンダーとイベントのカーソルもこのエラーを使います。カーソルを外してやり直してください。
`409`	`physical_series_ambiguous`	セレクターが複数の系列に一致します。
`409`	`limit_reached`	プランで許可されるWebhook送信先の上限に達しています。
`413`	`request_too_large`	リクエスト本文が大きすぎます。
`429`	`rate_limit_exceeded`	ネットワークまたはアカウントの短時間枠の上限に達しました。再試行は、次のヘッダーの指定に従って待機してから行ってください： `Retry-After`。
`429`	`quota_exhausted`	アカウントが月間リクエスト枠を使い切りました。
`500`	`internal_error`	Narwhalはリクエストを完了できませんでした。
`503`	`api_disabled`	公開データゲートは一時的に閉鎖されています。
`503`	`economics_unavailable`	Narwhalは受け入れ済み公式公開内容からリクエストを安全に満たせません。
`503`	`calendar_coverage_unavailable`	現在、カレンダーを安全に提供できません。
`503`	`database_unavailable`	データストアは一時的に利用できません。
`503`	`rights_state_changing`	Narwhal は、レスポンスの準備中にデータソースの利用許諾が変わっていないことを確認できませんでした。
`503`	`predictions_unavailable`	現在、予測データを安全に提供できません。
`503`	`upstream_unavailable`	現在、価格またはレートのデータを読み取れません。
`503`	`palmoil_unavailable`	現在、パーム油データを安全に提供できません。
`503`	`physical_price_unavailable`	現在、現物価格データを安全に提供できません。
`503`	`physical_reference_unavailable`	現在、現物系列データを安全に提供できません。
`503`	`rate_limiter_unavailable`	Narwhalはレート制限を確認できませんでした。少し待って再試行してください。
`503`	`command_unavailable`	現在、アカウントのコマンドを完了できませんでした。
`503`	`webhook_unavailable`	現在、Webhookを提供できません。

クォータヘッダー

成功したデータレスポンスはクォータを正確に1回消費し、次を含みます：

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

通常のヘッダーが示すリクエスト枠は 5,000件です（UTC の暦月単位）。認証済みレスポンスの短時間枠ヘッダーが示す Free アカウントの上限は毎分30リクエスト。別の不正利用防止用バケットでは、1つのネットワーク識別子につき毎分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リファレンス。