Skip to main content
Every failure is {"error": {"code", "message"}} with a matching HTTP status. The message says what to fix. The key is checked first: a request with a bad key is a 401 whatever else is wrong with it.
One 400 is not JSON: a query value of the wrong type, such as limit=abc or days=1.5, is refused before the route runs, with a plain-text body (Failed to deserialize query string: …). Send integers where the reference says integer and true/false for booleans.
404 on GET /tokens/{chain}/{address} means the token is unknown. 503 means the data could not be loaded this time: retry after Retry-After, and do not treat it as “does not exist”. When a read fails, the API keeps answering from its last good copy for a couple of minutes before it returns 503.
Both 503s above carry a Retry-After header, in seconds. Wait that long, then send the same request again: for a page, with the same cursor. A cursor that keeps failing (a 400, or a 503 again and again) while the first page loads will not heal: start the walk again from the first page. See Pagination.

Live errors

On the WebSocket, a wrong subscribe or op answers a frame of type error, with the id of the subscription:
When token, candles, trending, holders or traders cannot read its first data, it sends an error frame instead of the snapshot, with the code the REST route would give (a token channel on an unknown token: not_found). A token channel stops after that error; candles goes on with live candles; trending, holders and traders send the snapshot as soon as a read succeeds. trades and wallet never fail this way: they send what they could read as the snapshot, possibly empty, and keep streaming. A wallet subscription past the server’s limit of live wallets gets an error with code rate_limited and ends. On SSE, wrong parameters answer 400 JSON before the stream starts. Later errors are error events; on token the error ends the stream, so close the EventSource instead of letting it reconnect. While the server is at capacity, it refuses new connections, before the WebSocket upgrade or before the SSE stream starts, with 503 and Retry-After: 30:
Sockets and streams already open keep running, and an open socket can still subscribe. A browser WebSocket cannot read the status: it only sees the connection fail. An EventSource does not retry a 503 on its own. Reconnect after 30 s, with backoff.