Errors - Securitize Developers

How an error looks

{ "error": "TOKEN_NOT_FOUND", "message": "No token with id '7f3b2c10-5d4e-4a6b-9c8d-1e2f3a4b5c6d'", "statusCode": 404 }

Branch on error, never on message. A malformed request answers with message as a list of every field to fix:

{ "error": "Bad Request", "message": ["each value in status must be one of the following values: OPEN, CLOSED, UNAVAILABLE"], "statusCode": 400 }

A body with error_description, or a bare {"message": "..."}, comes from the gateway before the request reaches the API: check the bearer token (Sandbox and authentication).

Not found

An id that does not exist and an id outside your account answer the same way, so a caller never learns what exists.

Status	`error`	Meaning
`404`	`TOKEN_NOT_FOUND`	Unknown token, not linked to your account, or not a CET
`404`	`ASSET_NOT_FOUND`	Unknown asset, or none of its tokens is linked to your account; with `chainId`, none on that chain
`404`	`CA_NOT_FOUND`	Unknown corporate action, or one on an asset none of your tokens belongs to
`404`	`CA_VERSION_NOT_FOUND`	The corporate action exists but has no such version
`404`	`WEBHOOK_EVENT_NOT_FOUND`	Unknown event, another account’s, or older than 90 days
`404`	`WEBHOOK_ENDPOINT_NOT_FOUND`	No webhook endpoint is registered for your account yet; ask your Securitize contact

Bad requests

Status	`error`	Meaning
`400`	`Bad Request`	A parameter or field is malformed; `message` lists them. `status=ACTIVE` on `GET /tokens` is the common one: the filter takes `OPEN`, `CLOSED`, `UNAVAILABLE`
`400`	`EVENT_TYPES_NOT_ALLOWED`	None of `eventTypes` is a webhook event type Securitize publishes, of any family; `message` lists the valid names
`400`	`INVALID_RECOVER_WINDOW`	`since` is in the future or more than 90 days ago, or `until` is not after `since`
`401`	`UNAUTHORIZED`	The token is valid but the account it identifies is not known to this API; contact Securitize

Limits and faults

Status	`error`	Meaning	What to do
`429`	`RATE_LIMITED`, or no body	A resend was rate limited, or you are over 20 requests a second or 1,000 a minute	Wait `Retry-After` seconds
`422`	`WEBHOOK_PROVIDER_REJECTED`	The event history refused the request	Check the parameters; contact Securitize if it persists
`502`	`WEBHOOK_PROVIDER_UNAVAILABLE`, `PARTNER_REGISTRY_UNAVAILABLE`, or a generic body	A fault on Securitize’s side	Retry with backoff

Treat a code you do not recognise as a refusal of that call.

What is safe to retry

Call	Repeat it
Every `GET`	Safe
`POST /events/recover`	Safe. Resends are deduplicated by your handler on `sourceEventId`
`POST /sandbox/events`	Safe, but each call is a new run with new events

Getting help

When you contact Securitize about a response, send the operation and the time of the call, the ids involved (tokenId, sourceCaId, sourceEventId), and the error, message and statusCode you received. Never send your client secret or your webhook signing secret.