# Errors, retries and recovery

API errors use `{ "error": { "code": "…", "message": "…", "requestId": "…" } }`
with optional field errors, destination errors, retry hints and action handoffs.
Preserve `requestId` for support. Do not log credentials, signed upload URLs or
sensitive request content when collecting diagnostics.

| Response | Recovery |
|---|---|
| `401 unauthenticated` | Check missing, malformed or revoked product key |
| `403 forbidden_scope` / `account_not_allowed` | Review key scopes and destination access |
| `402 account_limit`, `seat_limit`, `storage_limit` | Review workspace entitlement and resource use |
| `402 subscription_inactive` / `trial_expired` | Resolve billing state; preserve drafts and queued work |
| `409 revision_conflict` | Read the current version, review changes and intentionally reapply |
| `409 idempotency_conflict` | The key was reused with a different body; reconcile the original operation |
| `409 consent_required` | Ask an authorized person to complete the supplied review handoff |
| `409 too_late_to_cancel` | Inspect actual delivery status; do not claim cancellation succeeded |
| `media_expired` / `media_deleting` | Re-upload originals and update the draft |
| `422 validation_failed` | Correct structured fields or per-destination issues |
| `429 rate_limited` | Respect `Retry-After`; reduce concurrency and use backoff |
| `submission_unknown` | Reconcile the existing external outcome before attempting another submission |

## Safe mutation retries

Generate an idempotency key before the first mutation and store its exact request.
If the response is lost, the operation may already have succeeded. Replay the
same request with the same key; never generate a fresh key merely because the
network timed out. MCP mutating tools echo their key, including in
`transport_outcome_unknown` failures. The adapter does not auto-retry mutations.

Technical workspace speed limits are not posting credits. Use `/usage` for the
current plan and rate information. Back off for transient errors only when
appropriate; retrying authorization, validation or human-consent errors without
changing their cause does not help.

## Partial success and observation

An accepted publish/schedule batch is a set of independent deliveries. Keep
successful receipts and native links. Recover a failed destination through its
own retry endpoint instead of creating the whole batch again. Prefer signed
[webhooks](/docs/webhooks); if polling, use a bounded number of attempts with
increasing delays and surface unresolved work to a person.
