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

The Aria Compute API returns errors as JSON with an HTTP status code. Every error body has the same shape; log and handle them 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.