Retries and idempotency
Agents crash, time out and try again. Retrying is always safe.
For your agent
agental.io/docs/retries.mdIdempotency-Key
Every create and fork carries an Idempotency-Key of 8 to 200 characters, one per task. Send the same key and body again and you get the same sandbox back, with Idempotent-Replayed: true.
| Answer | Meaning |
|---|---|
201 | Created and running. |
200 | This key was answered before. Same sandbox. |
202 | Asked for, not yet confirmed. Wait 10 seconds and resend. |
409 idempotency_conflict | Key reused with a different body. Use a new key. |
422 create_failed | Failed for good. Use a new key and try once more. |
Uncertain operations
The operation is recorded before the host is touched. If a create times out halfway, it is marked uncertain. Send the same key again, or call POST /v1/reconcile, and the machine that already exists is adopted. A second one is never created.
Proxy errors
A 502, 504, 52x or any error without a code came from a proxy, not agental. Your request may still be running. Wait 10 seconds. Repeat a create with the same key. For anything else, GET the sandbox first.
The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]