Errors - Securitize Developers

A refusal does not close the socket. A refused order costs an order, not the session. Only a failed hello, a well-formed message before the session is open, and an oversized frame close it. A malformed frame answers MALFORMED and the socket stays open, before hello as after.

How an error looks

{
  "type": "error",
  "requestId": "7a02c4e158b34f9da0e23c6b1d7f8e45",
  "traceId": "partners-rt-gw-4d81e0a7-2c6f-4b19-9e3a-8f5d1c7b0a62",
  "sentAt": "2026-08-28T15:29:47.012Z",
  "payload": {
    "code": "INVALID_ORDER",
    "message": "The reference ref-2026-08-28-0001 already names an order (FILLED): look it up instead of placing it again"
  }
}

Branch on code; message is for people and can change. The error carries the requestId of the message that caused it when the frame could be parsed far enough; a frame refused at envelope level (a malformed envelope, duplicate keys) gets an error without it. Quote traceId when you contact Securitize.

What to do

`code`	Socket	Meaning	What to do
`SIGNATURE_INVALID`	Closed, on `hello`	The signature does not verify, or the public key is not registered	Check that you sign the exact payload string you send, and that the key is registered. See Signing
`TIMESTAMP_OUT_OF_WINDOW`	Open	The `timestamp` is more than 30 seconds from the server clock	Fix NTP. Reconnecting does not help
`UNAUTHENTICATED`	Closed	A message arrived before the session was open	Send `hello` first and wait for `welcome`
`MALFORMED`	Open	Not parseable, a required field missing, or fields that contradict each other: a `MARKET` order with a `limitPrice`, both `quantity` and `notional` or neither. Also a second `hello` on an open session, and a malformed frame sent before `hello`	Fix the message
`INVALID_ORDER`	Open	Well formed and refused on its merits, with the reason in `message`: a duplicate `externalRef`, a buy your own cash cannot cover, a `MARKET` buy, an order by `notional`, `Insufficient buying power`, a sell your redemption balance or the redemption wallet cannot cover, a symbol your account does not trade (mistyped or not), or the broker’s own refusal in its words	A duplicate may be your own earlier order: look it up with `get_order` by `externalRef`. Otherwise fix the order, fund your cash or transfer the CETs, then send it again
`NOT_PERMITTED`	Open	The key is registered as read-only: it may read and receive pushes, but not `place_order`, `cancel_order` or `submit_crypto_funding`	Trade with a key registered for trading
`INVALID_SYMBOL`	Open	On `place_order`: a symbol your account trades that the broker no longer recognises; `message` names it. On `get_redemption_address` and `get_redemption_balance`: the symbol and chain are not ones you can trade, or (address only) the CET cannot be redeemed	Check it against `get_symbols`
`ORDER_NOT_FOUND`	Open	No such order on the session’s account	Check the id. By `externalRef`, after an `UNKNOWN`: the order never reached the broker, and resending it is safe
`ORDER_NOT_CANCELLABLE`	Open	The order’s state does not allow it: already filled or cancelled. `message` carries the broker’s words	Read the order
`UPSTREAM_UNAVAILABLE`	Open	The broker could not be reached, or a buy’s cash or a sell’s redemption wallet could not be checked. The fate of an order sent with it is unknown. On `hello`: the key could not be checked at that moment. On `submit_crypto_funding`: the chain could not be read, or no answer came in time	Look the order up with `get_order` by `externalRef` before resending. On `hello`, send a new `hello` with a new `nonce` on the same socket. On `submit_crypto_funding`, send the same `txHash` again: it is never credited twice
`DEPOSIT_PENDING`	Open	On `submit_crypto_funding`: the transaction is not on chain yet, or not final. Nothing was credited	Send the same `txHash` again later
`DEPOSIT_REFUSED`	Open	On `submit_crypto_funding`: the deposit will not be credited as sent. `message` says why: crypto funding is not enabled on that chain, there is no USDC transfer from one of your wallets to Securitize’s, the transaction failed, or it was already credited to another account	Nothing to retry. See Fund your cash with crypto
`RATE_LIMITED`	Open	The service is throttling requests	Retry after a pause
`INTERNAL`	Open	A fault on Securitize’s side, not a problem with the request	Retry with backoff; if it persists, contact Securitize with the `traceId`

Treat a code you do not recognise as a refusal of that message, not as a reason to drop the session. The reads over HTTP answer the same codes, with an HTTP status.

Close codes

Code	Meaning	What to do
`4001`	Authentication failed or expired. Also sent, with reason `UNAUTHENTICATED` and no `error` first, when no valid `hello` arrives within 10 seconds of connecting	Check the key and the signature, send `hello` first, then open a new session
`4008`	Policy: the socket was idle for 3 minutes	Keep sending `ping`, then reconnect
`1009`	A frame over 64 KB. No `error` is sent first	Keep every frame under 64 KB, then reconnect
`1001`	The server is going away, usually a release	Reconnect with backoff and reconcile
`1006`, or any other	The connection dropped or closed	Reconnect with backoff and reconcile

What is safe to retry

Message	Send it again
`place_order`	Safe with the same `externalRef`: a reference an order already uses is refused, never duplicated, except that the reference of an order refused before it reached the broker can be used again. A reference the broker itself refused stays taken for the rest of the day: resending it answers `INVALID_ORDER` as a duplicate, so use a new one. After `UNKNOWN`, resend it unchanged or look it up; after `UPSTREAM_UNAVAILABLE`, look the order up first
`cancel_order`	Safe. After an `UNKNOWN`, read the order instead
`submit_crypto_funding`	Safe with the same `txHash`: a transaction is credited once, and sending it again answers the same credit
Reads and `ping`	Safe
`hello`	With a new `nonce`: on the same socket after `UPSTREAM_UNAVAILABLE` or `TIMESTAMP_OUT_OF_WINDOW` (fix the clock first), otherwise on a new socket

Getting help

When you contact Securitize about a message, send:

the traceId of the reply or push;
your externalRef, and the orderId and regulatoryId if you have them;
the message type, when you sent it, and whether it was sandbox or production;
the code you received, and what you expected instead.

Never send your private key. The traceId is enough for Securitize to find the exchange.