Skip to main content
Decide what to do with a status code Albus returned. Every error response is JSON. Most carry a single field:
A 502 from a failed run adds "kind", naming the failure class.

​
Status codes

A 504 is a server-side timeout with a JSON body, which is how you tell it apart from a transport timeout: a transport timeout has no body.

​
Authentication errors in detail

Albus accepts two credentials, both as Authorization: Bearer <value>: /whoami accepts either and names whichever signed the request: user for a bearer token, api_key for a key. GET /health needs no credential.

​
Retrying safely

Every retry of an invocation must carry the Idempotency-Key of the invocation it retries. Without a key, a retry is a second invocation, and it spends a second run.
  • Same key, identical body → re-attaches to the invocation.
  • Same key, different body → 409.
  • New key while an invocation is running → 423.
  • No key → a fresh invocation; the response’s Idempotency-Key header carries the key the server assigned.
The SDKs and the CLI call that key the invocation key (invocation_key=, invocationKey:, --invocation-key); over HTTP it is the Idempotency-Key header, and it is what GET /traces/{invocation_key} reads an invocation back by.

​
In the SDKs

Every non-2xx status raises a typed error carrying status_code, message, and body — errors.AlbusError and its subclasses in Python, the errors module in TypeScript. See SDKs for the retry configuration and its interaction with long-polling runs.