NoLimitNodesDocs
Yellowstone gRPC

Yellowstone Errors and Limits

Handle gRPC status codes, message limits, filter limits, and reconnects.

Read the gRPC status code before choosing a response.

Status codes

CodeMeaningYour action
UNAUTHENTICATEDMissing or invalid credentialCheck x-api-key or SDK token
PERMISSION_DENIEDPlan or policy blocks the requestReduce scope or review access
INVALID_ARGUMENTFilter or request shape is invalidFix the request
NOT_FOUNDTopic or resource does not existRefresh the catalog
RESOURCE_EXHAUSTEDLimit reachedReduce filters or concurrent streams
UNAVAILABLETemporary service or network failureReconnect with backoff
DEADLINE_EXCEEDEDUnary request timed outRetry within a bounded budget
INTERNALServer failed to process the requestRetry once, then record diagnostics

Message size

Blocks and transactions exceed common client defaults.

For the TypeScript SDK:

const client = new Client(  "https://grpc.nln.clr3.org:443",  process.env.NLN_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 UNAUTHENTICATED without replacing the key.
  • Do not retry INVALID_ARGUMENT without 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.