Errors
JSON-RPC error codes returned by the Stream API
Every method and subscription returns the same error envelope. When something goes wrong, the server replies with a JSON-RPC error object that mirrors the request id. error.code is the JSON-RPC code; error.data.code is the application-level code emitted by handlers — that is the string clients should key off.
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "Invalid params",
"data": {}
}
}Codes
error.code | Name (data.code) | When |
|---|---|---|
-32700 | PARSE_ERROR | The payload is not valid JSON. |
-32600 | INVALID_REQUEST | The payload is not a valid JSON-RPC 2.0 envelope. |
-32601 | METHOD_NOT_FOUND / NOT_FOUND (HTTP 404) | No handler matches method, or a handler threw NOT_FOUND (data.code: NOT_FOUND). |
-32602 | INVALID_PARAMS / BAD_REQUEST (HTTP 400) | params failed schema validation, or a handler threw BAD_REQUEST (data.code: BAD_REQUEST). |
-32603 | INTERNAL_ERROR / INTERNAL_SERVER_ERROR (HTTP 500) | An unexpected server error (data.code: INTERNAL_SERVER_ERROR / SERVICE_UNAVAILABLE). Safe to retry with the same id after a short delay. |
-32401 | UNAUTHORIZED (HTTP 401) | The session is not authenticated, or the API key was revoked. |
-32403 | FORBIDDEN (HTTP 403) | The API key is missing the permission required for the method or topic. |
-32429 | TOO_MANY_REQUESTS (HTTP 429) | You exceeded the rate limit. Back off and retry after the retryAfterMs hint. |
Handling
-32602(BAD_REQUEST/INVALID_PARAMS) — log the request and the schema-validationdatapayload, then fix the client. These errors mean a bug, not a transient failure.-32401/-32403— re-runauthenticatewith a fresh signature. If-32403persists, the API key needs a new permission.-32429(TOO_MANY_REQUESTS) — readdata.retryAfterMsand wait at least that long before retrying. Apply exponential backoff if you keep hitting it.-32603(INTERNAL_SERVER_ERROR/SERVICE_UNAVAILABLE) — retry with the sameidafter a short delay; if it persists, contact support with the requestidand timestamp.
Notification errors
Subscriptions are push-only — the server does not send error objects on a topic. If a subscription fails (revoked permission, dropped connection), you stop receiving notifications and must resubscribe after re-authenticating.