Errors
Every error has the same envelope: a stable code, a human message, retryable, the request_id and a doc_url that links to its entry on this page.
{
"error": {
"code": "quota_exceeded",
"message": "…",
"retryable": false,
"next_action": "upgrade",
"request_id": "req_…",
"doc_url": "https://api.sisoco.co.uk/docs/errors#quota_exceeded"
}
}
A 429 or 503 that should be retried later carries Retry-After (seconds). details lists validation problems for invalid_request; provider names the upstream source for upstream errors.
next_action
| Value | Do this |
|---|---|
retry | Retry the same request, after Retry-After when present. |
top_up | Add prepaid credit, then retry. |
ask_owner | A person who owns the account must change something: a key, a mandate, a card. |
upgrade | A plan limit is reached: a higher plan lifts it, or wait for the reset. |
stop | Do not retry this request as sent. |
Codes
| Code | HTTP | Retryable |
|---|---|---|
invalid_request | 400 | no |
invalid_version | 400 | no |
unauthorized | 401 | no |
vertical_not_enabled | 403 | no |
ip_not_allowed | 403 | no |
origin_not_allowed | 403 | no |
insufficient_scope | 403 | no |
watch_limit_reached | 403 | no |
not_found | 404 | no |
ambiguous_match | 409 | no |
quota_exceeded | 429 | no |
rate_limited | 429 | yes |
upstream_rate_limited | 503 | yes |
upstream_unavailable | 502 | yes |
upstream_timeout | 504 | yes |
upstream_schema_changed | 502 | no |
provider_unavailable | 503 | yes |
pack_degraded | 503 | yes |
budget_exceeded | 402 | no |
authentication_required | 402 | no |
payment_method_required | 402 | no |
payment_failed | 402 | no |
mandate_scope | 403 | no |
idempotency_conflict | 409 | no |
internal_error | 500 | yes |
invalid_request HTTP 400
The request failed validation: a missing or malformed parameter or body field, or a malformed Idempotency-Key. details lists each problem with its path.
What to do: Fix the request as details says; retrying it unchanged will fail again.
invalid_version HTTP 400
The Sisoco-Version header is not a supported API version.
What to do: Send a version listed in the changelog, or omit the header to use your pinned version.
vertical_not_enabled HTTP 403
The route, tool or event type belongs to a pack (vertical) your account does not have.
What to do: Add the pack to your plan, or ask for beta access. The request was not charged.
ip_not_allowed HTTP 403
The key has an IP allowlist and the request came from another address.
What to do: Call from an allowed address, or change the key's allowlist on the account page.
origin_not_allowed HTTP 403
The request reached the origin directly instead of through the public API address.
What to do: Use the public base URL.
insufficient_scope HTTP 403
The key is read-only and the request writes (watchlists, webhooks).
What to do: Use a read-write key; the account owner creates one on the account page. next_action: ask_owner.
watch_limit_reached HTTP 403
The watchlist add would exceed the plan's watched-entity limit. Nothing was added. details gives limit, watched and adding.
What to do: Remove watched entities or upgrade the plan (next_action: upgrade). Watched entities are never billed as overage.
not_found HTTP 404
No such record (a definitive "not found" from the register is charged like an answer), or no such resource in your account.
What to do: Check the identifier; do not retry unchanged.
ambiguous_match HTTP 409
GET /v1/check found several candidates for a name. details.candidates lists them ranked by confidence.
What to do: Check again with a registry number or LEI from the candidates.
quota_exceeded HTTP 429
The plan's monthly lookups are used up (and no prepaid credit is left), or the keyless trial's daily allowance is used. Retry-After says when it resets.
What to do: Upgrade, buy a credit pack, or wait for the reset (next_action: upgrade). Without a key: get a free key.
rate_limited HTTP 429, retryable
Too many requests: the key's per-minute burst limit for its usage tier, the account's share of a provider's capacity, the free tier's daily upstream capacity, an agent key's purchase velocity, or repeated failed authentications.
What to do: Wait for Retry-After and retry (next_action: retry); next_action says when waiting will not help.
upstream_rate_limited HTTP 503, retryable
The official source's own rate limit or our shared budget for it is used up.
What to do: Retry after Retry-After.
upstream_timeout HTTP 504, retryable
The official source did not answer in time, after retries.
What to do: Retry later. The request was not charged.
upstream_schema_changed HTTP 502
The official source's answer no longer matches the schema we validate it against. We never guess at changed data.
What to do: Do not retry; we are alerted and fix the adapter. The request was not charged.
pack_degraded HTTP 503, retryable
The pack's health check is failing; only this pack is affected.
What to do: Retry after Retry-After; /v1/catalog shows the pack status.
budget_exceeded HTTP 402
An agent credential's mandate would be exceeded: its monthly budget or its per-purchase ceiling, checked against the spend ledger before every metered call and every charge.
What to do: The account owner raises the budget by minting a new agent key (next_action: ask_owner).
authentication_required HTTP 402
The bank asked for Strong Customer Authentication on an off-session charge. Nothing was charged; the owner has been emailed a link to complete it.
What to do: Wait for the owner to authenticate, then retry with a new Idempotency-Key (next_action: ask_owner).
payment_method_required HTTP 402
There is no saved card for off-session charges.
What to do: The owner saves one on the account page (POST /v1/billing/payment-method).
payment_failed HTTP 402
The card was declined. Nothing was charged.
What to do: The owner updates the card in the billing portal (next_action: ask_owner).
mandate_scope HTTP 403
The credential's mandate does not cover this action: a missing scope (read, watch, purchase), a pack outside the mandate, or an owner-only route (hosted checkout, billing portal, saving a card).
What to do: The owner mints an agent key with the needed scope (next_action: ask_owner).
idempotency_conflict HTTP 409
The Idempotency-Key was used before with a different request, or the first request with this key is still running.
What to do: Use a new key for a different request (next_action: stop); retry shortly if the first is still running (next_action: retry).
internal_error HTTP 500, retryable
Something failed on our side. It is logged with the request_id.
What to do: Retry with backoff; quote the request_id if it persists.