> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error reference

> HTTP status codes, error response format, and retry guidance for the Gateway.

The Gateway returns standard HTTP status codes with a JSON error body. This page covers the error format, common status codes, and retry strategies.

## Response format

### Successful response

```json theme={"system"}
{
  "data": { ... },
  "error": "",
  "code": "successful"
}
```

### Error response

```json theme={"system"}
{
  "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)                              |

<Warning>
  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.
</Warning>

## 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.