Request cost and error codes

This page covers how much of the daily quota a call uses and the machine-readable labels an error carries. For status codes, Retry-After and a retry pattern, see Rate limits and errors.

One call, one request

Every call to a data endpoint uses one request from the account's daily quota, whatever the response size. /api/v1/... and /api/v2/... draw on the same counter at the same price.

A call counts once the key is accepted, whatever the outcome. Each of these uses one request, and nothing is refunded:

a 404 for an identifier that resolves to nothing;

a 422 for a bad parameter;

a 502 from a failing upstream.

A call that stops before that point does not count:

a 401 for a missing or unknown key;

a 404 for a path that does not exist;

a 422 for a request body that is not valid JSON.

System endpoints (/health, /about, /services, /sources) are public and never count.

Hosted MCP tools

Calls through the hosted MCP server draw on the same quota. A gateway tool that calls a data endpoint (call_endpoint, fetch_data) costs what that call costs: one request. The composed tools have a fixed cost:

Tool	Cost per call
`resolve_entity`	1
`get_timeseries`	1
`get_snapshot` with `company_snapshot`, `etf_snapshot` or `earnings_snapshot`	2
`get_snapshot` with `quote_snapshot`, `macro_indicator_snapshot`, `macro_calendar` or `debt_snapshot`	1

A composed call is charged before it runs:

A snapshot that comes back partial costs the same as a complete one.

A snapshot that fails because a required component is unavailable is not refunded.

When fewer requests are left than the call costs, the call is refused and nothing is charged.

Quota headers

Every response to a data call made with an accepted key carries the counter, errors included:

x-ratelimit-limit: 5000
x-ratelimit-remaining: 4213
x-ratelimit-reset: 2026-09-27T23:59:59Z

x-ratelimit-limit is the plan's daily requests.

x-ratelimit-remaining is what is left for the account today, all keys together.

x-ratelimit-reset is the end of the current UTC day.

The 429 for a spent quota carries them too, with x-ratelimit-remaining: 0. A call that stops before the key is accepted (the 401, 404 and 422 cases listed above) and a system endpoint carry no rate-limit headers.

Rarely, while our usage counter is unavailable, each server enforces a conservative share of the daily limit instead, and x-ratelimit-remaining counts that share rather than the account's day. A 429 in that state says the limit is temporarily reduced and carries Retry-After: 60 and x-ratelimit-remaining: 0, even when the day's quota is not spent. Wait and retry: the full limit returns when the counter does.

Error labels

Branch on the status code first. Where a body carries a stable label, it is in one of these places.

`code` on a 401

The body names the case in code: missing_api_key, invalid_api_key, or unauthorized for any other authentication failure. reason explains it in words. See Authentication for a full body.

`detail.error` on upstream failures and on endpoint families

A failing upstream answers with a typed object whose detail.error is one of upstream_error, upstream_shape_unexpected, upstream_unreachable, upstream_deferred, upstream_timeout, lane_busy, upstream_too_large or upstream_rejected_request. The table in Rate limits and errors says which of them a retry helps.

Several endpoint families use the same place for their own cases, for example on the ETF, options and SEC filing endpoints:

{
  "detail": {
    "error": "unknown_symbol",
    "symbol": "XYZQ",
    "hint": "GET /api/v1/etf/snapshot/universe lists the covered symbols."
  }
}

The label names the case and the status says what to do. A 4xx such as unknown_symbol or invalid_symbol_format will not change on retry. A 503 such as snapshot_not_available or universe_not_initialised usually clears after a backoff.

`detail.code` on NetAtlas endpoints

The network endpoints (/api/v1/network/...) answer with {"detail": {"code": "...", "message": "..."}}:

Status	`code`
400	`INVALID_IP`, `INVALID_PREFIX`, `BAD_PREFIX`, `INVALID_HOST`, `INVALID_SOURCE`, `INVALID_PREFER`, `INVALID_RESOURCE`, `MISSING_QUERY`, `QUERY_TOO_SHORT`, `MISSING_FILTER`, `BLANK_FILTER`, `BAD_FILTER`, `BAD_COUNTRY`, `BAD_TYPE`, `MISSING_ASN`
404	`ASN_NOT_FOUND_IN_ATLAS`, `DOMAIN_NOT_FOUND_OR_UNSUPPORTED_TLD`
502	`UPSTREAM_FAILED`, `RESOLVER_FAILED`
503	`ATLAS_DEGRADED`, `HIJACK_SOURCE_DEGRADED`

The bulk lookups (POST /api/v1/network/bulk/ip and /bulk/asn) answer 200 and report failures per item:

A failed item carries error with the same code and message, or INTERNAL.

An item left when the time budget ran out carries "unprocessed": true, and the response sets partial to true.

`endpoint_removed` on a 410

A removed endpoint answers 410 with a Deprecation: true header and points to its replacements:

{
  "detail": {
    "error": "endpoint_removed",
    "message": "The economic events calendar was removed.",
    "see": ["/api/v1/macro/releases", "/api/v1/ons/releases"]
  }
}

It needs no key and does not count.

`response_shape_invalid` on a 500

The API produced an answer its own schema refuses. The body carries "error": "response_shape_invalid", the route, and a retry_hint. The same request returns the same answer until we fix it, so do not retry it in a loop.

Request cost and error codes

One call, one request#

Hosted MCP tools#

Quota headers#

Error labels#

code on a 401#

detail.error on upstream failures and on endpoint families#

detail.code on NetAtlas endpoints#

endpoint_removed on a 410#

response_shape_invalid on a 500#