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 complete approved economics publication 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.
`401`	`invalid_api_key`	The Bearer key is missing, malformed, unknown, or inactive.
`404`	`series_not_found`	No complete approved publication matches 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.
`405`	`method_not_allowed`	The route exists but does not accept the requested HTTP method.
`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`	`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.

Quota headers

Every successful data response consumes quota exactly once and includes:

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

The reset is the start of the next UTC calendar month. A 429 also includes Retry-After. Responses with 400, 401, 404, 405, 429, 500, or 503 do not consume 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.