---
title: "Errors and credits — Narwhal API"
description: "Handle Narwhal API problem responses, stable error codes, credit headers, rate limits, and retries."
url: "https://narwhalapi.com/docs/errors"
---

# Errors and credits

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

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

## 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 or belongs to different filters. |
| `400` | `invalid_pair` | The from and to currencies are the same. |
| `401` | `invalid_api_key` | The Bearer key is missing, malformed, unknown, or inactive. |
| `402` | `insufficient_credits` | Your balance does not cover this call. The call did not run and cost nothing. Add credit at the `top_up_url` in the response. |
| `404` | `series_not_found` | No approved current or historical observations match the request. |
| `404` | `resource_not_found` | The requested command resource is unavailable. |
| `404` | `event_not_found` | No event matches the id. |
| `404` | `not_found` | No calendar release matches the id. |
| `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. |
| `404` | `subscription_not_found` | The calendar subscription id is unknown or not yours. |
| `404` | `physical_series_not_found` | No physical price series matches the id. |
| `404` | `palmoil_series_not_found` | No palm oil series matches the id. |
| `404` | `webhook_request_failed` | The webhook destination is unknown, or the delivery cannot be replayed. |
| `405` | `method_not_allowed` | The route exists but does not accept the requested HTTP method. |
| `409` | `cursor_expired` | The cursor expired or its snapshot is unavailable. Calendar and events cursors also use this error. Restart without the cursor. |
| `409` | `physical_series_ambiguous` | The selector matches more than one series. |
| `409` | `limit_reached` | The account'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 per-minute limit was reached; retry after `Retry-After`. |
| `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. |
| `503` | `upstream_unavailable` | Price or rate data cannot be read right now. |
| `503` | `palmoil_unavailable` | Palm oil data cannot be served safely right now. |
| `503` | `physical_price_unavailable` | Physical price data cannot be served safely right now. |
| `503` | `physical_reference_unavailable` | Physical series data cannot be served safely right now. |
| `503` | `rate_limiter_unavailable` | Narwhal could not check your rate limit. Retry shortly. |
| `503` | `command_unavailable` | The account command could not be completed right now. |
| `503` | `webhook_unavailable` | Webhooks cannot be served right now. |

## Credit headers

Every call that is charged returns the cost of the call and your balance after it. Both are in US dollars with six decimals.

`X-Request-ID` `X-Narwhal-Cost` `X-Narwhal-Balance` `X-RateLimit-Limit` `X-RateLimit-Remaining` `X-RateLimit-Reset`

`X-Narwhal-Cost` is what this call took from your balance, for example `0.002000` for one Economics call. `X-Narwhal-Balance` is your free, bonus and paid credit added together. Errors and responses that say nothing changed cost nothing.

The `X-RateLimit-*` headers describe the per-minute limit only. The limit is 50 requests a minute while your account has only free credit, and 500 requests a minute once it holds paid credit. A request for several ids is one request. 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` and costs nothing.

## When your credit runs out

A call that your balance cannot pay for is refused with `402 insufficient_credits`. It carries the cost of the call, your balance and a link to add credit.

402 insufficient_credits

```
{
  "type": "https://narwhalapi.com/docs/errors#insufficient_credits",
  "title": "Insufficient credits",
  "status": 402,
  "code": "insufficient_credits",
  "detail": "This call costs $0.002. Your balance is $0.000. Top up at https://narwhalapi.com/dashboard/billing",
  "top_up_url": "https://narwhalapi.com/dashboard/billing",
  "cost_micro": 2000,
  "balance_micro": 0
}
```

`cost_micro` and `balance_micro` are whole millionths of a dollar, so 2000 is $0.002. Do not retry a 402 until the balance has changed. Free credit renews on the first day of each month.

## Retry behavior

- Do not retry `400` until the request is corrected.
- Do not retry `402` until you have added credit.
- 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](https://narwhalapi.com/docs/quickstart.md) or review the [Economics API reference](https://narwhalapi.com/docs/api/economics.md).

Was this page helpful?
