{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Errors","description":"Write your own software to control Collective2","keywords":"documentation,api,automated trading,Collective2 API Documentation","lang":"en-US","siteUrl":"https://c2-api.redocly.app/","meta":[{"name":"charset","content":"utf-8"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"errors","__idx":0},"children":["Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before upgrade, authentication and connection/admission errors are HTTP responses. After"," ","upgrade, application errors arrive as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," envelopes. A transport failure or a forced close"," ","can occur without a final application error message."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-the-upgrade","__idx":1},"children":["Before the Upgrade"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP status"},"children":["HTTP status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid API key"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit or per-API-key connection limit reached"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server connection capacity unavailable"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-WS-Error"]}," carries a short description. A simultaneous connection race can reject a socket"," ","just after upgrade with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PolicyViolation"]},", without an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," envelope; wait and check existing"," ","connections before retrying. Do not assume every policy close has the same cause."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validation-and-correlation","__idx":2},"children":["Validation and Correlation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An account request can report several field errors together:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"msg_type\": \"error\",\n  \"id\": \"msg_675d3f4bbc7e4f27aadd0db8444f\",\n  \"request_id\": \"bad-account-sub\",\n  \"timestamp\": \"2026-10-26T15:00:00Z\",\n  \"v\": 4,\n  \"payload\": {\n    \"errors\": [\n      {\n        \"code\": \"MANDATORY_PARAM_EMPTY_OR_MALFORMED\",\n        \"field\": \"payload.account\",\n        \"message\": \"Missing parameter\"\n      },\n      {\n        \"code\": \"INVALID_PARAMETER\",\n        \"field\": \"payload.broker_id\",\n        \"message\": \"Invalid parameter\"\n      }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single error uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.code"]},", optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},". Multiple errors use the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.errors"]}," array. Echoed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," associates a rejection with its request even while"," ","other data and heartbeats are arriving."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Account validation"},"children":["Account validation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Result"},"children":["Result"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing/blank ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.account"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MANDATORY_PARAM_EMPTY_OR_MALFORMED"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account longer than 45 characters"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_PARAMETER"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing, zero or negative ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.broker_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_PARAMETER"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Explicit zero or negative ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.person_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_PARAMETER"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Any account ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.resume_from"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_PARAMETER"]}," because account replay is unsupported"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unknown action/channel, malformed envelope or timestamp outside one minute of UTC"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validation error on the affected field"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omitted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["person_id"]}," uses the authenticated session person; an explicit value does not grant"," ","access to someone else's account. Authorization checks the selected exact account/broker owner"," ","and current channel permissions/site authority."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"subscription-errors","__idx":3},"children":["Subscription Errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning and action"},"children":["Meaning and action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FORBIDDEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account/strategy authority denied. Correct access before retrying"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ALREADY_EXISTS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The channel and physical identity are already subscribed or pending. A different person override does not create a second account subscription"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unsubscribe requested an identity not currently subscribed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOO_MANY_SUBSCRIPTIONS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The relevant account or strategy limit was reached. Unsubscribe unused identities first"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SERVICE_UNAVAILABLE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The initial account snapshot or server connection capacity is unavailable. Retry the subscription with backoff"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOO_MANY_REQUESTS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request rate exceeded. After upgrade, delay and retry the request while keeping the healthy connection"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FRAGMENT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unsupported WebSocket fragmentation or invalid JSON"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNKNOWN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unexpected server error. Retain diagnostic IDs and contact API support"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An unsubscribe acknowledgement follows a successful explicit unsubscribe. A pending account"," ","subscription can fail before its acknowledgement if the initial snapshot is unavailable."," ","A missing update does not clear existing orders or positions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"access-revocation","__idx":4},"children":["Access Revocation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Changes to API-key or account access can close the connection. If an active account subscription"," ","is no longer authorized, the server"," ","removes it and sends an unsolicited ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.ack"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action: \"unsubscribe\""]},", its channel,"," ","account, broker ID and person ID. It has no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]},". Stop using that channel's"," ","cached state; do not automatically resubscribe in a tight loop. A denial before activation"," ","returns a correlated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FORBIDDEN"]}," error instead."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Other subscriptions can remain active when one channel is removed. Correlate requested"," ","acknowledgements by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," and handle unsolicited ones separately."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"heartbeat-slow-consumers-and-transport-failures","__idx":5},"children":["Heartbeat, Slow Consumers and Transport Failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A missed application heartbeat can close with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NormalClosure"]}," and reason ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Ping timeout"]},"."," ","Slow consumption can produce that same reason, so it does not uniquely identify the cause."," ","Do not infer an exact close deadline from the close code or reason."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The server can close a slow connection with reason"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Outbound queue full. Reconnect and resubscribe"]},". Transport failures or server shutdown can"," ","end a connection without an application error. A normal close code can still require recovery."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Process incoming messages promptly, acknowledge JSON heartbeats, and move blocking REST,"," ","storage or computation work outside the receive loop. Protocol Ping/Pong does not replace"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["heartbeat.ack"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reconnection-guidance","__idx":6},"children":["Reconnection Guidance"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Situation"},"children":["Situation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid fields or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FORBIDDEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Correct the cause; keep other healthy subscriptions running"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duplicate subscription"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the existing subscription or unsubscribe it before replacing it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Snapshot ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SERVICE_UNAVAILABLE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry that subscription with backoff; connection may remain usable"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit after upgrade"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delay the request. Reconnecting is unnecessary"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transport close or eviction"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reconnect with exponential backoff and jitter, then use the channel-specific rule below"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authority revoked"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mark affected state unavailable and obtain corrected authority before resubscribing"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strategy.signal"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strategy.live_fills"]},", retain separate successfully processed cursors"," ","and request bounded replay. For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strategy.positions"]},", resubscribe and replace the full collection."," ","For every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account.*"]}," channel, resubscribe ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["without"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resume_from"]}," and replace state from the new"," ","initial snapshot. Clear stale account state rather than merging the old socket's baseline."," ","See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/websocket-gap-fill"},"children":["Recovery and Gap Fill"]},"."]}]},"headings":[{"value":"Errors","id":"errors","depth":1},{"value":"Before the Upgrade","id":"before-the-upgrade","depth":2},{"value":"Validation and Correlation","id":"validation-and-correlation","depth":2},{"value":"Subscription Errors","id":"subscription-errors","depth":2},{"value":"Access Revocation","id":"access-revocation","depth":2},{"value":"Heartbeat, Slow Consumers and Transport Failures","id":"heartbeat-slow-consumers-and-transport-failures","depth":2},{"value":"Reconnection Guidance","id":"reconnection-guidance","depth":2}],"frontmatter":{"title":"Errors","description":"Validation, authorization changes, subscription errors and channel-specific recovery","seo":{"title":"Errors"}},"lastModified":"2026-10-29T23:04:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/websocket-errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}