cubestechdocsdashboard ↗

Program Streams Errors and Reconnects

Common status codes

CodeCauseYour action
UNAUTHENTICATEDMissing or invalid API keyReplace the key
PERMISSION_DENIEDPolicy blocks the topicCheck account and policy scope
NOT_FOUNDTopic name is staleRefresh ListTopics
INVALID_ARGUMENTTopic or format is malformedFix the request
RESOURCE_EXHAUSTEDAccount limit reachedClose unused subscriptions
UNAVAILABLETemporary transport failureReconnect with backoff
INTERNALServer processing failedRetry once, then record details

Reconnect flow

  1. Store the last processed slot.
  2. Close the failed channel.
  3. Wait with exponential backoff and jitter.
  4. Refresh topics after catalog errors.
  5. Open a fresh TLS channel.
  6. Subscribe again.
  7. Deduplicate overlap in storage.

Program Streams do not accept a replay slot.

For gap-sensitive systems, pair the stream with Yellowstone or RPC reads.

Schema changes

Hash the proto_schema response.

When the hash changes:

  1. Pause deployment.
  2. Regenerate payload clients.
  3. Decode stored fixtures.
  4. Resume consumers after tests pass.

Backpressure

Do not run slow database work inside the gRPC data callback.

Place events in a bounded queue. Stop or restart the stream when the queue reaches its limit.