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

# Errors

> The error envelope and status codes.

Every error returns a consistent envelope:

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "Human-readable reason.",
    "correlationId": "b7c1…"
  }
}
```

Quote the `correlationId` when contacting support.

## Status codes

| Status | Code                                 | Meaning                                                                        | Your action          |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------ | -------------------- |
| `400`  | `bad_request`                        | Invalid input (bad chain, missing field, unknown strategy, malformed address). | Fix the request.     |
| `401`  | `unauthorized`                       | Missing or invalid API key on a partner endpoint.                              | Check your key.      |
| `404`  | `not_found`                          | Unknown route or strategy.                                                     | —                    |
| `429`  | `rate_limited`                       | Rate tier exceeded.                                                            | Honor `Retry-After`. |
| `503`  | `upstream_unavailable` / `not_ready` | Transient — market data too stale, no swap route, RPC hiccup, or warming up.   | Retry with backoff.  |

## Build failures fail closed

The build endpoints never return a half-built transaction. A caller-fixable problem is a `400`; a transient upstream issue is a `503` (retryable). The `message` states the specific reason.