The Gateway returns standard HTTP status codes with a JSON error body. This page covers the error format, common status codes, and retry strategies.
Successful response
Error response
HTTP status codes
A 200 response can still carry an operation failure. Check the error field in every response body. For example, POST /transaction/send returns 200 even when the observer rejects the transaction.
Common errors by category
Address errors
Transaction errors
Block errors
VM query errors
Observer failover
If the primary observer for a shard fails, the Gateway retries with the next observer in the rotation. If all observers for a shard are unavailable, the Gateway returns 500.
The Gateway never retries the same observer on failure. It moves to the next one immediately, keeping latency predictable and preventing request pile-up on an unhealthy node.
Retry guidance
- 400 errors: fix the request parameters. Do not retry.
- 500 errors: retry with exponential backoff (1s, 2s, 4s, max 30s). The observer may be overloaded or restarting.
- 503 errors: retry after 5 to 10 seconds. The Gateway is starting up and observers are syncing.
- Timeouts: retry with backoff. The Gateway has a configurable request timeout, and timeouts typically indicate the observer is under heavy load.
For transaction status polling, use a 2 to 3 second interval. Blocks finalize every ~6 seconds, so polling faster than that yields no additional information. 
