Errors

The API fails loudly and specifically: errors carry a status code and a structured detail explaining what went wrong. This page covers the errors you'll actually encounter and the right response to each. Endpoint-specific triggers are documented on each capability page.

Status codes at a glance

Two contract-level guarantees worth knowing:

• Failed billable requests are refunded automatically. If a request fails after its cost was deducted, the deduction is reversed as part of error handling. See credits.
• Empty is not an error. A 200 with an empty result list means "nothing matched your filters" — often a signal that a filter is too tight or an entity name silently resolved to the wrong identity (see below).

401 — authentication

For REST: the request is missing the Authorization: Bearer header, or the key is invalid or deleted. For MCP: the client's OAuth session is missing or expired — reconnect and sign in again. See Authentication.

402 — insufficient credit

The request would exceed your balance, so it was rejected before any work ran — nothing partial happened. Top up and retry the identical request.

422 — the request can't be processed as asked

The most informative error class. The recurring cases:

unresolved_entities

An entity name didn't match any known canonical name. The detail includes suggestions — candidate canonical names found by similarity:

• Tickers (TSLA) always fail — entity inputs take canonical names, not symbols.
• Treat suggestions as hints to verify, not confirmed identities.
• The reliable fix: copy canonical_name exactly from a prior result. See Entities.

insufficient_entity_activity

The name resolved, but the entity has too little recent activity for a meaningful package (entity retrieval). Frequent cause: a short name ("Tesla") matched a different, sparse identity than the one you meant ("Tesla, Inc."). Retry the fuller legal-style name before concluding the entity is quiet. No charge applies — the cost is refunded.

Timestamp validation

• A start_timestamp in the future is rejected — there is nothing to query there. (A future end_timestamp is valid and means realtime; see point-in-time semantics.)
• Alert arguments must not contain start_timestamp/end_timestamp — the alert owns its rolling window.

Other validation

Empty required strings, out-of-range parameters, invalid filter combinations — the detail names the offending field and constraint.

404 — not found

Beyond plain wrong ids, two cases worth knowing:

• As-of queries can legitimately 404: retrieving a development as of a timestamp before it first existed returns 404 — correct point-in-time behavior, not a data gap.
• Source URLs (/source/...) return 404 for any unknown or invalid link, including a bad access key.

Handling guidance

• Branch on status code; log the detail — it is written to be actionable.
• Retry 5xx (with backoff) and 402-after-top-up. Don't blind-retry 422 — the same request will fail the same way until changed.
• For agents: 422 details, especially entity suggestions, are designed to be fed back into a corrected call. One correction loop resolves most cases.