Errors and quota

Handle Narwhal problems by HTTP status and stable machine-readable code.

REST errors use application/problem+json. MCP tool errors carry the same problem fields in structured content.

Problem response

Branch on status first and code second. Treat detail as human-readable diagnostic text, not a stable programmatic value.

RFC 9457 problem

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

Statuses and codes

Status	Public code	Meaning
`400`	`invalid_query`	The country, period, or other request input is invalid.
`400`	`invalid_cursor`	The pagination cursor is malformed, expired or tied to different filters.
`401`	`invalid_api_key`	The Bearer key is missing, malformed, unknown, or inactive.
`403`	`plan_upgrade_required`	Requested history exceeds your plan's window (Free: 12 months; Basic: 5 years); upgrade for more.
`404`	`series_not_found`	No approved current or historical observations match the request.
`404`	`route_not_found`	The requested REST route does not exist.
`404`	`tool_not_found`	The requested MCP tool is not public or does not exist.
`404`	`calendar_not_published`	The requested country-year calendar has not been published.
`404`	`commodity_not_supported`	This commodity code is unavailable for spot prices or bars.
`404`	`currency_not_supported`	This commodity is not quoted in the requested currency.
`405`	`method_not_allowed`	The route exists but does not accept the requested HTTP method.
`409`	`limit_reached`	Your plan's webhook destination limit has been reached.
`413`	`request_too_large`	The request body is too large.
`429`	`rate_limit_exceeded`	The network or account short-window limit was reached; retry after `Retry-After`.
`429`	`quota_exhausted`	The account has used its monthly request allowance.
`500`	`internal_error`	Narwhal could not complete the request.
`503`	`api_disabled`	The public data gate is temporarily closed.
`503`	`economics_unavailable`	Narwhal cannot safely satisfy the request from an accepted official publication.
`503`	`calendar_coverage_unavailable`	The calendar cannot be served safely right now.
`503`	`database_unavailable`	The data store is temporarily unavailable.
`503`	`rights_state_changing`	Narwhal could not confirm that source permission stayed unchanged while preparing the response.
`503`	`predictions_unavailable`	Prediction data cannot be served safely right now.

Quota headers

Every successful data response consumes quota exactly once and includes:

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

The regular headers describe the 3,000-request UTC-month allowance. On authenticated responses, the short-window headers describe the Free account limit of 30 requests per minute. A separate abuse-protection bucket allows 120 requests per minute with a burst of 20 for one network identity, so clients sharing an address can be throttled together. A 429 rate_limit_exceeded includes Retry-After for the limiting short window; a 429 quota_exhausted waits for the next UTC calendar month. Neither response consumes monthly quota.

Retry behavior

Do not retry 400 until the request is corrected.
Do not retry 401 with the same rejected key.
Retry 429 only after Retry-After or X-RateLimit-Reset.
Retry idempotent requests after 500 or 503 with bounded exponential backoff and jitter.
A 404 series_not_found may become available only after a supported official release is published.

Ask for help

Send the endpoint, UTC time, status, code, and request_id to Narwhal API support. Never include the API key.

Return to the quickstart or review the Economics API reference.