The JSON-RPC and HTTP error contract for Starkscan RPC — codes, envelopes, backoff, and fail-closed classes.

RPC errors

After an authenticated request reaches the RPC handler, Starkscan returns a JSON-RPC 2.0 result or error object. An HTTP authentication rejection also uses a JSON-RPC error member, so standard clients such as starknet.js throw normally. Authentication still uses the appropriate HTTP status and WWW-Authenticate challenge. The gateway rejects authentication before it trusts the request envelope, so these errors use "id": null.

Transport & protocol codes

Code	Meaning	When
`-32700`	Parse error	Malformed JSON body
`-32600`	Invalid request	Bad envelope; `authentication_invalid` for malformed or conflicting authentication headers; also `batch_too_large` (>50 items) with `data.maxItems`. Do not retry an unchanged authentication request.
`-32601`	Method not found	Method not in the allowlist (e.g. a mistyped `starknet_*` name)
`-32602`	Invalid params	Params fail validation (shape, bounds, felt format)
`-32603`	Internal error	Unexpected server error (rare; carries a request id)

Starknet execution errors (e.g. 20 contract-not-found, 40/41 execution errors, 55 validation) are passed through in the error object unchanged, so starknet.js decodes them normally.

Gateway-specific JSON-RPC codes

These codes are emitted by the Starkscan gateway. An upstream provider can also return its own JSON-RPC codes, so branch on the structured error.data.code when you need the precise condition.

Code	`error.data.code`	Meaning	Client action
`-32004`	`unsupported_chain`	The URL names a chain this endpoint does not serve.	Correct the URL; do not retry unchanged.
`-32005`	`upstream_unavailable`, `local_saturation`, `authorization_unavailable`, or `batch_response_too_large`	The upstream or authorization provider is temporarily unavailable, the gateway is saturated, or an aggregate batch result exceeded 16 MiB.	Honor `Retry-After` when present; split an oversized batch before retrying.
`-32010`	`rate_limited`	The RPC quota for the request or batch item is exhausted.	Honor the delay and reduce request rate.
`-32011`	`write_scope_required`	A write method needs an eligible write scope.	Use an eligible key and an already-signed payload; do not retry unchanged.
`-32012`	`authentication_required` or `scope_required`	The key is missing or invalid, or a read/simulation request needs the documented access scope.	Use an eligible key; do not retry unchanged.

Authentication errors on non-2xx

POST /api/v1/{chain}/rpc returns a JSON-RPC error object for authentication failures while preserving HTTP 400, 401, 403, or 503. HTTP 401 and 403 retain WWW-Authenticate; retryable 503 responses retain Retry-After when the failed authentication path supplies a delay:

{"jsonrpc":"2.0","id":null,"error":{"code":-32012,"message":"Authentication required","data":{"code":"authentication_required","requestId":"mzk-…","service":"starkscan_rpc_gateway","httpStatus":401}}}

REST routes retain the REST error envelope. requestId is also emitted as the X-Request-Id header on every route. Include it in any support report.

Backoff

Inspect every JSON-RPC item for an error object, including batch responses with HTTP 200.
Honor Retry-After whenever it is present, regardless of the HTTP status. Gateway throttling and local saturation also expose the delay as error.data.retryAfterSeconds.
Do not hot-loop when no retry delay is supplied; treat it as a bounded transient failure and apply your own capped backoff.
X-Ratelimit-Limit / -Remaining / -Policy let you pace before you hit the ceiling. X-Starkscan-Rpc-Class tells you which budget a method draws from.

Bounded-payload errors

Large-payload methods fail closed with a typed error instead of returning an oversized body — split the request and retry (no blind loops):

Method	Cap	Error
`starknet_getStorageProof`	32 total proof targets; per-field sub-caps	`storage_proof_response_too_large`
`starknet_getCompiledCasm`	4 MiB serialized item	`compiled_casm_response_too_large`
`starknet_traceTransaction`, `starknet_traceBlockTransactions`	16 MiB serialized item	`trace_response_too_large`
batch	50 items and 16 MiB aggregate serialized response	`batch_too_large` or `batch_response_too_large`

trace_response_incomplete means the upstream trace omitted or malformed a field required by the Starknet trace schema. Starkscan rejects that response instead of returning incomplete execution evidence.

Fail-closed classes

Methods outside the current success surface return an explicit error naming the class — they never partially succeed:

starknet_traceTransaction / starknet_traceBlockTransactions without an operator-issued trace entitlement or enrolled trace-certified partner policy → rpc_trace; both entitlement forms use separate bounded quotas
starknet_subscribe* / starknet_unsubscribe over HTTP → rpc_ws (use the WSS route)
write methods without a write-scoped key → rpc_write

What to include in a bug report

HTTP status · the JSON-RPC result or error · X-Request-Id · X-Starkscan-Rpc-Class · X-Ratelimit-* · whether you used header or node-URL auth. Never include the full key or the full node-URL.

RPC errors

On this page