# Yellowstone Errors and Limits

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

Canonical: https://nolimitnodes.com/docs/api-reference/grpc/errors-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(
  "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.