---
slug: developer-api-reliability-errors
title: Idempotency, retries, errors, and limits
category: capability
status: published
tags: [idempotency, idempotency key, retry, duplicate, error, 402, 409, limits, 幂等, 重试, 错误码, 限制]
aliases: []
lastEditAt: 2026-08-02
---
## 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.

## Next steps

- [Create and read Tasks](/help/developer-api-create-read-tasks)
- [Authentication and workspace billing](/help/developer-api-authentication-billing)