errors.mdx

title	Errors
description	Error codes from the gRPC and RPC endpoints, and when to retry.

gRPC

When a gRPC stream is refused or ended by the service, the response carries:

• a gRPC status code,
• an x-error-code header or trailer with one of the codes below,
• a status message ending in (code: …) with the same code.

Code	gRPC status	Meaning	What to do
UNAUTHENTICATED	16 UNAUTHENTICATED	The key is missing, invalid, expired or revoked, or the key's access rules block this address	Fix the key or its rules. Do not retry
NOT_ENTITLED	7 PERMISSION_DENIED	The account has no active plan or trial for this product	Buy a plan or request a trial
IP_NOT_ALLOWED	7 PERMISSION_DENIED	This source IP is not bound to a plan for this product	Bind the IP under Plans → Allowed IPs
QUOTA_EXCEEDED	8 RESOURCE_EXHAUSTED	The plan's data allowance is used up	Buy more data or a fixed-price plan
AUTH_RATE_LIMITED	8 RESOURCE_EXHAUSTED	Too many failed authentication attempts from this address	Fix the key, then retry later
AUTH_BUSY	14 UNAVAILABLE	Authentication is shedding load	Retry with backoff
AUTH_UNAVAILABLE	13 INTERNAL	Credentials could not be checked right now	Retry with backoff
NO_CAPACITY	14 UNAVAILABLE	No capacity is free to serve the stream right now	Retry with backoff
UPSTREAMS_UNAVAILABLE	14 UNAVAILABLE	The service is temporarily unavailable	Retry with backoff
UPSTREAM_ERROR	14 UNAVAILABLE	The request did not complete	Retry with backoff
INVALID_CONTENT_TYPE	3 INVALID_ARGUMENT	The request was not gRPC	Use a gRPC client
REQUEST_TOO_LARGE	3 INVALID_ARGUMENT	The subscribe request is larger than the service accepts	Send fewer filters
NO_REQUEST	1 CANCELLED	No subscribe request arrived before the stream closed or timed out	Send the subscribe request as soon as the stream opens
SLOT_NOT_RETAINED	11 OUT_OF_RANGE	from_slot is older than the oldest slot kept for replay	Subscribe from a newer slot, or without from_slot
BAD_UPSTREAM_REQUEST	13 INTERNAL	The request could not be forwarded	Retry with backoff

UNAUTHENTICATED, NOT_ENTITLED, IP_NOT_ALLOWED and QUOTA_EXCEEDED also end streams that are already open. Revoking a key, a plan expiring, removing an IP or running out of data ends a running stream within about 30 seconds, with the matching code.

Reading the code

let code = status.metadata().get("x-error-code").and_then(|v| v.to_str().ok());

const code = /\(code: ([A-Z_]+)\)/.exec(error.message)?.[1];

code := stream.Trailer().Get("x-error-code")

RPC

Errors raised by the RPC service itself use HTTP status codes and a JSON-RPC error body:

{ "jsonrpc": "2.0", "error": { "code": -401, "message": "Unauthorized. Invalid or expired API key." }, "id": null }

The limits your plan sets also return an x-error-code header, so a client can tell them apart without reading the message.

HTTP	Code	x-error-code	Message	What to do
401	-401		Unauthorized. API key required. …	Send your key
401	-401		Unauthorized. Invalid or expired API key.	Check the key, its access rules and that you have an RPC plan, package or trial
402	-402	QUOTA_EXCEEDED	The request allowance for the current window has been reached …	Your credits are used up. Add a credit pack, renew the RPC plan or buy a package
429	-429	RATE_LIMITED	Too Many Requests. Rate limit exceeded for your plan.	Slow down, or raise your plan's request rate
429	-429	SEND_RATE_LIMITED	Too Many Requests. Your plan allows N sendTransaction calls per second.	Space out your sends, or move to a larger package
429	-429		Too Many Requests	Back off and retry
502	-502		Bad Gateway	Retry
503	-503	NO_CAPACITY	No capacity is free to serve this request right now. …	Retry after the Retry-After delay. Not your plan limit
504	-504		Gateway Timeout	Retry, or narrow the request
413	-413		Payload Too Large	Keep the request body at 1 MiB or less, or split the batch
405			Method not allowed	Use POST

Errors about the request itself, such as invalid parameters or an unknown method, come back as standard Solana JSON-RPC errors with HTTP 200.