AiVideoEditor
Start for free
Menu

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.

ResponseRecovery
401 unauthenticatedCheck missing, malformed or revoked product key
403 forbidden_scope / account_not_allowedReview key scopes and destination access
402 account_limit, seat_limit, storage_limitReview workspace entitlement and resource use
402 subscription_inactive / trial_expiredResolve billing state; preserve drafts and queued work
409 revision_conflictRead the current version, review changes and intentionally reapply
409 idempotency_conflictThe key was reused with a different body; reconcile the original operation
409 consent_requiredAsk an authorized person to complete the supplied review handoff
409 too_late_to_cancelInspect actual delivery status; do not claim cancellation succeeded
media_expired / media_deletingRe-upload originals and update the draft
422 validation_failedCorrect structured fields or per-destination issues
429 rate_limitedRespect Retry-After; reduce concurrency and use backoff
submission_unknownReconcile 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.