Errors
Every status the API returns, what causes it, and what to do next.
Errors are JSON. Validation errors follow FastAPI's shape (a detail array); everything
else returns a detail string or object.
Status codes
| Status | Meaning | What to do |
|---|---|---|
200 | Success. | — |
400 | The Authorization header is missing or is not a Bearer token. | Fix the header. |
401 | Key rejected — wrong, revoked, or the account's 30-day request allowance is spent. | Check rate limits before assuming the key is bad. |
402 | Not enough credits for this call. | Top up. The call did not run and was not charged. |
404 | No entity with that id. | Ids are UUIDs; a malformed id also returns 404, not 422. |
422 | A parameter failed validation. | Read detail[].loc for the offending field. |
429 | Per-minute limit exceeded. | Back off until X-RateLimit-Reset. |
500 | The request reached the endpoint and the endpoint failed. | See below — some 500s are caused by the request. |
503 | A dependency is unavailable. | Retry with backoff. |
Validation errors
{
"detail": [
{
"type": "less_than_equal",
"loc": ["query", "limit"],
"msg": "Input should be less than or equal to 100",
"input": "101"
}
]
}500s you can cause yourself
Two situations return 500 where a 4xx would be more accurate. Both are worth guarding
against in your client:
- An unrecognised
event_typesvalue when creating a monitoring subscription returns500 {"detail": "Failed to create watchlist subscription"}. Send only the values listed under monitoring. - Subscribing to a company you already monitor returns the same
500. ReadGET /monitorsfirst, or treat this500as "already subscribed".
Retrying
Retry 429, 500 and 503 with exponential backoff. Do not retry 400, 401, 402,
404 or 422 — they will not succeed on a second attempt.
`Idempotency-Key` does not make a write idempotent
The header is accepted, but it only deduplicates the billing event. The request still
runs. Two POST /lists/ calls carrying the same Idempotency-Key create two lists
and are charged once — verified against production.
So retrying a write is not safe, whatever header you send. Before retrying a POST,
re-read the collection and check whether the first attempt landed — a timeout on our side
does not mean the write did not happen.