Idempotency, retries, and limits
Every write carries an Idempotency-Key header of at most 200 characters.
Tycoon hashes the normalized request body against that key, so retrying the
same call is safe, and reusing a key with a different body is refused rather
than silently doing something else.
| Write | First accepted | Same-body replay | Key reused with a different body |
|---|---|---|---|
POST /tasks | 201 | 200, idempotent_replay: true | 409 |
POST /tasks/{id}/messages | 202 | 200 | 409 |
POST /tasks/{id}/actions/{approval_id}/resolve | 202 | 200 | 409 |
Retry a lost or timed-out write with the same key and the same body. A 409
while an identical request is still in flight means the first attempt is being
processed — read the Task instead of minting a new key. Reads are safe to
repeat at any time; between reads of an unfinished Task, honor poll_after_ms.
The documented limits are the request-field ceilings enforced on create and
message (prompt and message 20,000 characters, title 200,
working_guidance 12,000, outcome.target 8,000, budget_usd 100,000, ids
200) and the idempotency-key length above. There is no published request-rate
limit; workspace spend authority, not a request quota, is what stops paid work.
Error contract
| Status | Meaning |
|---|---|
400 | Invalid JSON/body or missing/invalid idempotency key |
401 | Missing, invalid, revoked, or expired API key |
402 | API key controller workspace cannot authorize more paid work, or a published key's allocated Task budget is exhausted |
403 | Key lacks scope or its user is no longer a workspace member |
404 | Task or requested workspace is absent, unauthorized, unbound, belongs to another controller, or was not API-created |
409 | Idempotency conflict, unavailable Metric/Playbook/action, stale action version, an action requiring interactive resolution, in-flight duplicate, terminal Task, or unavailable Astra |
Task ids are not bearer capabilities. Every read and write is joined to the authenticated key's controller workspace and to the successful public create receipt, which records the immutable execution workspace separately.