HTTP status codes and error responses - Aria Compute

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

{ "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.

⌘I