Errors and Limits
Read the gRPC status code before choosing a response.
Status codes
| Code | Meaning | Your action |
|---|---|---|
UNAUTHENTICATED | Missing or invalid credential | Check x-api-key or SDK token |
PERMISSION_DENIED | Plan or policy blocks the request | Reduce scope or review access |
INVALID_ARGUMENT | Filter or request shape is invalid | Fix the request |
NOT_FOUND | Topic or resource does not exist | Refresh the catalog |
RESOURCE_EXHAUSTED | Limit reached | Reduce filters or concurrent streams |
UNAVAILABLE | Temporary service or network failure | Reconnect with backoff |
DEADLINE_EXCEEDED | Unary request timed out | Retry within a bounded budget |
INTERNAL | Server failed to process the request | Retry once, then record diagnostics |
Message size
Blocks and transactions exceed common client defaults.
For the TypeScript SDK:
typescript
const client = new Client(
"geyser.sol.cubestech.online:443:443",
process.env.NODE_API_KEY,
{ grpcMaxDecodingMessageSize: 64 * 1024 * 1024 },
)Pick a limit large enough for your filters. Keep an upper bound to protect memory.
Reconnect policy
- Retry
UNAVAILABLE, connection resets, and transport timeouts. - Do not retry
UNAUTHENTICATEDwithout replacing the key. - Do not retry
INVALID_ARGUMENTwithout changing the filter. - Add random jitter.
- Cap backoff at 30 seconds.
- Restore filters after each connection.
- Request replay from your last stored slot.
Record useful diagnostics
Log:
- gRPC status code
- Status detail
- Endpoint
- Filter names
- Requested commitment
- Last processed slot
- Client package version
Never log your API key or full sensitive account lists.