Sisoco Oneby Sisoco Partners

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

ValueDo this
retryRetry the same request, after Retry-After when present.
top_upAdd prepaid credit, then retry.
ask_ownerA person who owns the account must change something: a key, a mandate, a card.
upgradeA plan limit is reached: a higher plan lifts it, or wait for the reset.
stopDo not retry this request as sent.

Codes

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.

unauthorized HTTP 401

No valid API key: the key is missing (on a route that needs one), malformed, revoked or expired.

What to do: Send Authorization: Bearer <key> with a live key. Get a free read-only key with POST /v1/preview/keys, or create one on the account page.

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_unavailable HTTP 502, retryable

The official source failed or could not be reached, after retries.

What to do: Retry later. The request was not charged.

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.

provider_unavailable HTTP 503, retryable

The provider is switched off (licence or configuration) and answers nothing.

What to do: Use another provider listed in /v1/catalog, or retry later.

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.