Stellar errors

Stellar on Triport has two transports, Soroban JSON-RPC and Horizon REST/SSE, and each reports errors in its own envelope. This page lists the Stellar-specific answers — the retention boundary, the Horizon page-size limit and methods outside the catalog — and which of them are worth retrying.

Endpoint and plans: Stellar RPC endpoint.

Authentication, tier and rate-limit failures are the same on every network and are described in the shared error reference: they are plain HTTP responses (401, 403, 429) decided before a request reaches a node.

Error table

Answer	Transport	Meaning	Retry?
HTTP `410 Gone`, `error=beyond_retention`, `oldest=N`	Horizon REST	The requested record is below the retained window of the node that served it.	No — clamp to `oldest`
JSON-RPC `-32602`, `beyond_retention`, `oldest N`	Soroban JSON-RPC	The same retention boundary, reported in the JSON-RPC envelope.	No — clamp to `oldest`
HTTP `400`, `limit must not exceed 200`	Horizon REST	The page size is above the Horizon maximum.	Only after lowering `limit` to 200 or less
JSON-RPC `-32601`	Soroban JSON-RPC	The method is absent from the published Soroban catalog.	No — check the method name
HTTP `403`, `method_unknown`	gate	The method is not part of the Stellar product; rejected before any node.	No
HTTP `429`, `rate_limited`	gate	The `stellar_read_rpc` or `stellar_read_rpc_heavy` budget is spent.	Yes, after `Retry-After`

Retention boundary

Stellar history on Triport lives in a measured window: Soroban keeps about 120,960 ledgers and Horizon 6,307,191 ledgers. Below it, Horizon answers 410 Gone with error=beyond_retention and oldest=N, and Soroban answers -32602 with beyond_retention and oldest N in the message. Both describe the same thing — the boundary of the node that served you — in two envelopes.

JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32602, "message": "beyond_retention: oldest 57926881" }
}

A retention response describes the available historical window. It is not an internal failure, and repeating the same out-of-window request will not recover the missing history. Read oldest from the response, clamp the query to it and page forward; for anything older, read from your own index. Never treat the error as an empty result: an empty list would let your code conclude that nothing happened in that range. The full walkthrough is on beyond_retention.

Horizon page size

Horizon list endpoints such as GET /payments and GET /operations return at most 200 records per page. limit=500 fails with HTTP 400 and limit must not exceed 200; it has nothing to do with retention. Ask for 200 or fewer and follow the paging cursor.

Methods outside the catalog

The Soroban surface is read-only and published as 10 methods; the JSON-RPC index lists them. A name outside that list gets JSON-RPC -32601. The gate-level method_unknown is a separate HTTP 403 rejection that never reaches the RPC layer. Both mean the call is not served here, so fix the method name or the network instead of retrying. The general causes of -32601 are on Method not found.

Rate limits

Heavy history reads (getEvents, getTransactions, Horizon payments and operations, and the SSE streams) are counted in stellar_read_rpc_heavy, separately from ordinary reads. A 429 names the category it ran out of; wait Retry-After seconds before retrying. Budgets per tier are on Stellar rate limits and tiers.