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
{
"data": { ... },
"error": "",
"code": "successful"
}
Error response
{
"data": null,
"error": "human-readable error message",
"code": "internal_issue"
}
HTTP status codes
| Status | Meaning | When it occurs |
|---|
| 200 | Success | Request processed. Check the error field for application-level errors. |
| 400 | Bad request | Invalid parameters, malformed address, missing required fields |
| 500 | Internal error | Observer unavailable, timeout, or unexpected server error |
| 503 | Service unavailable | Gateway not ready (observers still syncing) |
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
| Error | Cause | Fix |
|---|
invalid bech32 address | Malformed address string | Verify the address starts with erd1 and is valid bech32. |
could not get account | Observer returned empty | Check that the address exists on-chain. |
Transaction errors
| Error | Cause | Fix |
|---|
transaction generation failed | Missing or invalid fields | Verify all required fields (nonce, value, signature, etc.). |
invalid transaction signature | Signature does not match | Re-sign the transaction with the correct private key. |
insufficient balance | Sender cannot cover value + gas | Check the balance before sending. |
Block errors
| Error | Cause | Fix |
|---|
block not found | Nonce or hash does not exist | Verify the block nonce/hash is correct for the given shard. |
VM query errors
| Error | Cause | Fix |
|---|
invalid smart contract address | scAddress is not a contract | Verify the address is a deployed smart contract. |
function not found | funcName does not exist on the contract | Check the contract ABI for available view functions. |
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. 
