Reviewed 2026-11-10 · API version 2026-11-09 · Read Markdown
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; if polling, use a bounded number of attempts with increasing delays and surface unresolved work to a person.