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

Starknet errors

When the upstream node answers with an error the Starknet JSON-RPC spec lists for that method, such as 20 contract not found, 24 block not found, 29 transaction hash not found, 33 invalid continuation token, 40 contract error, or 41 transaction execution error, Starkscan returns it exactly as the spec defines it: the spec's canonical message and, only for codes whose spec defines one, the spec's data. starknet.js and starknet.go decode the revert reason normally:

{"jsonrpc":"2.0","id":1,"error":{"code":41,"message":"Transaction execution error","data":{"transaction_index":0,"execution_error":{"contract_address":"0x…","class_hash":"0x…","selector":"0x…","error":"… ('ERC20: transfer amount exceeds balance')"}}}}

• 40 carries data.revert_error; 41 carries data.transaction_index and data.execution_error. Both keep the call chain down to the raised error. A raised error longer than 16 KiB is cut and ends with [truncated by Starkscan]; a chain deeper than 64 frames ends with [call chain truncated by Starkscan] in place of its next frame. Codes whose spec defines no data, such as 24 or 29, carry none.
• Spec errors carry no Starkscan metadata. Use the X-Request-Id response header in a support report.
• A spec error is the node's answer, not an outage: a reverting estimate does not slow down or saturate any other request. When a provider reports an outage, overload, or rate limit under a spec code, or answers starknet_blockNumber / starknet_blockHashAndNumber with 32 (no blocks), Starkscan returns the retryable -32005 upstream_unavailable error instead, so it is never mistaken for a revert or an empty chain.
• Any other upstream error keeps the redacted gateway envelope: "message":"Starknet RPC upstream rejected the request" with error.data.code=upstream_json_rpc_error.
• Write-submission rejections keep a redacted envelope with error.data.code=upstream_write_rejected, because their data can echo signatures and calldata.

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.

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

Endpoint cooldown before any upstream response returns local_saturation. If the same request already received an upstream error and cooldown prevents its retry, Starkscan retains that failure under its normal error-priority and redaction rules rather than replacing it with local saturation. This applies to single reads and read batches; it does not increase retry or waiting limits.

• Inspect every JSON-RPC item for an error object, including batch responses with HTTP 200. A large history, simulation or trace batch is admitted in chunks, so local_saturation can affect only some of its children; retry just those items. The reason batch_deadline marks children that were not sent because the batch used up its time budget; retry them in a smaller batch.
• 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):

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.