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

# HTTP status codes and error responses

> Aria Compute API error shape, the full status-code table, and retry guidance for 4xx and 5xx responses.

The Aria Compute API returns errors as JSON with an HTTP status code. Every error body follows the same shape, so you can log and branch on it consistently.

## Error shape

```json theme={null}
{ "error": "message describing what went wrong" }
```

The exact message varies by endpoint. Never parse it for logic; branch on the HTTP status.

## Status codes

| Status                      | Meaning                                                                                            | What to do                                 |
| --------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `400 Bad Request`           | Missing or malformed field in the request.                                                         | Fix the request and retry.                 |
| `401 Unauthorized`          | Missing, expired, or invalid session token or API key.                                             | Re-authenticate or rotate the key.         |
| `403 Forbidden`             | Authenticated, but not authorized (for example, a non-admin calling an admin endpoint).            | Sign in with an authorized account.        |
| `404 Not Found`             | Resource does not exist or is not visible to this account.                                         | Check IDs, slugs, and per-site scoping.    |
| `409 Conflict`              | Request conflicts with existing state (for example, duplicate invoice).                            | Fetch current state and reconcile.         |
| `429 Too Many Requests`     | Rate limit exceeded.                                                                               | Back off and retry with exponential delay. |
| `500 Internal Server Error` | Unexpected server error.                                                                           | Retry with backoff. Report if persistent.  |
| `503 Service Unavailable`   | A dependency (typically PostgreSQL) is down. `/healthz` returns this when the database ping fails. | Retry with backoff.                        |

## Retry guidance

* Retry `429`, `500`, `502`, `503`, and `504` with exponential backoff and jitter.
* Do not retry `400`, `401`, `403`, `404`, or `409`. Fix the request instead.
* For long-running downloads that return `302`, retry the request (not the presigned URL): S3 links expire.

## Health check

`GET /healthz` returns `{ "status": "ok" }` when the database is reachable and `503 { "error": "database unavailable" }` otherwise. Use it as a liveness or readiness probe.


## Related topics

- [Aria Compute REST API reference](/api-reference/introduction.md)
- [POST /api/auth/phone/send-otp — send SMS verification code](/api-reference/auth/send-otp.md)
- [Python client for the Aria Compute API](/sdks/python.md)
- [GET /api/billing/payments/{id} — get payment status](/api-reference/billing/payments-get.md)
- [GET /api/api-keys — list your API keys](/api-reference/api-keys/list.md)