API reliability

Errors

REST errors use application/problem+json. MCP tool errors carry the same fields in structured content. Every problem has type, title, status, detail, code and request_id. Branch on status first and code second. detail is text for people and can change.

This request has no key. The response is a real one from the live API.

curl -i https://api.narwhalapi.com/v1/economics/usa/cpi

HTTP/2 401
content-type: application/problem+json
www-authenticate: Bearer realm="narwhal"
x-request-id: c6b42dc9-cb11-4ae8-9afa-c2bdf80eb62c

{
  "type": "https://narwhalapi.com/problems/invalid-api-key",
  "title": "Authentication required",
  "status": 401,
  "detail": "Provide a valid Narwhal API key as a Bearer token. No key? An AI agent can get one for its user at https://narwhalapi.com/auth.md, or sign up at https://narwhalapi.com/signup.",
  "code": "invalid_api_key",
  "request_id": "c6b42dc9-cb11-4ae8-9afa-c2bdf80eb62c"
}

The complete list of codes is on Errors and credits. When you ask support for help, send the endpoint, the UTC time, the status, the code and the request_id. Never send the API key.

Response headers

Rate limits

Each limit is a token bucket. It refills at the per-minute rate and holds at most the burst size. A request for several ids counts as one request.

Clients that share an address can be throttled together by the network limit. Free credit renews on the first day of each month.

An account can also run at most 2 history reads at the same time. These are the paged history, bars and observations operations over REST and MCP. A read that cannot get a slot within 2 seconds is refused with 429 rate_limit_exceeded and Retry-After: 1, before it is charged.

Retries

• Do not retry a 400 until the request is corrected.
• Do not retry a 401 with the same key.
• Do not retry a 402 until you have added credit.
• Retry a 429 only after Retry-After or X-RateLimit-Reset.
• Retry idempotent requests after a 500 or 503 with bounded exponential backoff and jitter.
• A 409 cursor_expired means start the pagination again without the cursor.

A 503 is a refusal to return uncertain data. Narwhal sends it instead of a guess, and the call costs nothing.

Versioning and deprecation

• The REST API version is in the path: /v1. There is no version header. MCP at /mcp negotiates its own protocol version. SDK versions are separate from the API version.
• Inside /v1, Narwhal can add endpoints, MCP tools, data sets, countries, optional inputs, optional or nullable response fields and new enum values at any time without notice. Ignore fields you do not know and accept enum values you do not know.
• Removing or renaming a field is a breaking change. So is changing its type, meaning, unit, precision or whether it is required, and changing a route, method, authentication, pricing or default behaviour. A breaking change ships as a new path, a new operation or a new major version.
• If a breaking change or removal affects an endpoint or field your account called in the last 90 days, Narwhal tells you at least 3 months before it takes effect, by email and on the changelog. Something no account called in the last 90 days can be removed with shorter notice, announced on the changelog.
• No removal date is set today.

Every change is listed in the changelog, which has an RSS feed. The full policy is on Versioning and deprecation.

Data freshness

Fresh means the latest complete official release that Narwhal has validated and published. A request reads Narwhal's stored current publication and does not call the official source, so a slow or down source does not slow your request.

A scheduled worker checks each source, validates the release, stores it, and only then makes the whole release the one customers get. An incomplete or invalid release is never mixed in. If a source check fails, Narwhal keeps the last accepted publication and retries on schedule. If it cannot safely serve a publication, the request fails with a documented 503.

Official agencies can revise a period, so a later accepted publication can replace a stored value. Headline economics figures may be provisional first estimates that the response does not mark as provisional. Narwhal does not promise a fixed delay between a source release and publication during the beta. More on Data freshness.