> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: Error codes
description: How a ShipContent error reaches an agent, what each code means, and the one next action for each.
section: contracts
order: 50
status: implemented
mode: both
reviewed: 2026-11-19
sources: [src/lib/server/owner/video-skills-access.ts, src/lib/server/billing/Credits.ts, src/lib/server/media/motion-billing.ts, src/lib/server/media/MotionStudioPaidAiHttp.ts, src/lib/server/media/FalOpusPlanner.ts, db/accounts.sql, src/lib/server/skills/skill-run-http.ts, src/lib/server/skills/SkillRuns.ts, src/lib/server/customer-error-response.ts, src/lib/i18n/customer-message.ts, db/media.sql, src/lib/server/media/technique-choice-http.ts, src/proxy.ts, db/retention.sql, scripts/billing-ops.ts, src/lib/server/billing/BillingOperator.ts, db/billing.sql, src/lib/server/billing/stripe-dispatch.ts, src/lib/server/billing/stripe-http-client.ts, src/app/api/billing/email-events/route.ts, src/lib/server/billing/BillingEmailEvents.ts, db/publishing.sql, src/lib/server/billing/StripeOwnerPlans.ts, src/lib/youtube/youtube.ts, src/lib/server/youtube/YouTubeService.ts, src/lib/server/youtube/YouTubeProvider.ts, src/lib/server/database/AppDatabase.ts, src/lib/server/auth/BetterAuth.ts, src/lib/server/auth/EmailSender.ts, src/lib/server/auth/PrincipalResolver.ts, src/lib/server/auth/TokenVerifier.ts, src/lib/server/advertising/read-store.ts, src/lib/server/advertising/execution.ts, src/lib/server/advertising/service.ts, src/lib/server/http.ts, src/lib/server/marketing/service.ts, db/instagram.sql, db/tiktok.sql, src/lib/effect.ts, src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/server/x/XPublishing.ts, src/components/owner/x-panel.tsx, db/x.sql, src/lib/server/media/MotionPlanner.ts, src/lib/server/media/MotionStudioPlanHttp.ts, src/lib/server/media/MotionDocuments.ts, src/lib/server/auth/AuthEmail.ts, src/lib/server/owner/owner-session.ts, src/lib/server/instagram/instagram-agent-tools.ts, src/lib/server/media/MotionSceneWriter.ts, src/lib/server/media/MotionTemplates.ts, src/lib/server/media/MotionTranscripts.ts, src/lib/server/media/MotionBrand.ts, src/lib/server/media/media-http.ts, src/lib/server/media/project-agent-tools.ts, src/lib/server/marketing/MarketingStore.ts, src/lib/marketing/post-catalogue.ts, src/lib/marketing/post-scheduling.ts, src/lib/server/marketing/PostScheduling.ts, src/components/owner/post-schedule-controls.tsx, src/worker/PostScheduleWorker.ts, src/lib/server/tiktok/TikTokInsights.ts, src/lib/server/tiktok/TikTokComments.ts, src/worker/TikTokReplyWorker.ts, src/worker/TikTokPublicationWorker.ts, src/lib/server/tiktok/TikTokPublication.ts, src/lib/server/tiktok/TikTokMedia.ts, src/lib/server/tiktok/TikTokAccounts.ts, src/lib/server/tiktok/TikTokAccountsPrivateDatabase.ts, src/lib/server/tiktok/TikTokAccountsVault.ts, src/lib/server/tiktok/TikTokAccountsProvider.ts, src/lib/server/x/x-database.ts, src/lib/server/lifecycle/MetaErasureDatabase.ts, db/meta.sql, src/lib/server/lifecycle/MetaErasureStatusDatabase.ts, src/lib/server/lifecycle/meta-lifecycle-route.ts, src/lib/server/lifecycle/meta-signed-request.ts, src/lib/server/lifecycle/MetaLifecycleCallback.ts, src/lib/server/instagram/InstagramLifecycle.ts, src/lib/server/marketing/PostSetPublishing.ts, src/lib/server/marketing/post-set-publish-checks.ts, src/lib/server/client-error.ts, src/lib/server/mcp/mcp-http-errors.ts, src/lib/native-studio-error.ts, src/lib/server/website/website-import-client.ts, scripts/start.mjs, scripts/failure-throttle.mjs, src/components/owner/billing-plan-section.tsx, src/lib/server/facebook/facebook-api-metrics.ts, src/lib/server/x/x-owner-approval.ts, src/lib/server/database/skill-run-reads.ts, src/lib/server/youtube/youtube-database.ts, src/lib/server/uploads/uploads-database.ts, src/lib/server/billing/PlanSelection.ts, src/lib/server/billing/stripe-database-query.ts, src/lib/server/billing/stripe-plan-error.ts, src/lib/server/billing/stripe-refill-common.ts, db/youtube.sql, src/lib/server/elevenlabs/ElevenLabsVault.ts, src/lib/server/elevenlabs/ElevenLabsConnection.ts, src/lib/server/elevenlabs/ElevenLabsPrivateDatabase.ts, src/lib/server/elevenlabs/ElevenLabsVoices.ts, src/app/api/elevenlabs/route.ts, src/worker/AccountVoiceProvider.ts, src/components/owner/elevenlabs-account-section.tsx, db/migrations/20261110T1900_elevenlabs_connection.sql, src/lib/server/media/MediaJobDatabase.ts, db/migrations/20261111T2000_elevenlabs_account_voice_replay.sql, db/migrations/20261112T0840_elevenlabs_worker_credential_presubmit.sql, db/migrations/20261112T2130_agent_instagram_destination.sql, src/lib/server/instagram/instagram-approval-database.ts, src/lib/server/uploads/DirectUploads.ts, src/lib/server/uploads/agent-image-upload.ts, db/migrations/20261119T0410_youtube_upload_reliability.sql, src/lib/server/youtube/YouTubeProviderUploads.ts, src/worker/YouTubeUploadOutcome.ts, src/lib/mcp/agent-post-publish-tools.ts, db/migrations/20261119T0400_agent_connected_account.sql, src/lib/server/marketing/post-metrics-agent-tools.ts, src/lib/server/marketing/PostMetrics.ts, db/migrations/20261119T0420_agent_delete_cancel_post.sql, src/lib/mcp/agent-post-lifecycle-tools.ts, src/lib/server/marketing/post-lifecycle-agent-tools.ts, src/lib/server/marketing/PostScheduleStore.ts, src/lib/marketing/post-lifecycle.ts, db/migrations/20261119T0440_facebook_token_refresh.sql, src/worker/TokenRefreshWorker.ts]
tools: [get_post, list_posts, inspect_post, list_assets, get_workspace, get_onboarding_status, get_media_job, list_media_jobs, list_media_uploads, start_instagram_connection, get_instagram_connection, prepare_instagram_readiness, get_instagram_readiness, ads_get_plan, ads_inspect_plan, ads_get_readiness, ads_get_approval_request, publish_instagram_reel, get_project, cross_post, get_post_metrics, refresh_post_metrics, delete_post, cancel_post_schedule]
next: [/docs/contracts/request-ids]
---

A failed MCP tool call returns `isError: true` and safe `structuredContent` with `{ code, error }`. The `error` sentence states the immediate problem. Do not copy a provider diagnostic, token, or storage URL into a new request. A successful call can still report readiness blockers or a queued job.

Updated October 19, 2026: the `error` sentence is written for the owner and the agent. It never names a server setting or tells the reader to change server configuration. When a feature is not available on this server, or the failure is internal, `error` is a general sentence and `code` does not change. An internal system code, such as a network failure code, becomes `SERVER_ERROR`. Saved error text on a website import, an asset, a transcript, a plan or a TikTok review follows the same rule. The operator reads the original detail in the server log.

Updated 2026-10-31: the account language never changes `code` or the English `error` sentence. MCP tool calls have no language input, and their output stays in English. A reply to an owner page in the browser can add a `localization` field. The app uses it to show the message in the account language; other clients can ignore it. Pages that a provider hosts, and the JSON or HTML replies of provider callbacks, do not change with the account language.

## Recovery by kind

Post planning (2026-10-16):

| Code | Next action |
| --- | --- |
| `PLANNER_RECEIPT_REQUIRED` | Recover only the receipt already saved for this generation. Ask an operator to inspect a lost submission receipt; do not submit again. |
| `PLANNER_RESULT_UNAVAILABLE` | Retry reading the original saved request. An unavailable response keeps its credit hold and does not authorize another provider submission. |


Stripe billing (2026-10-16; live mode 2026-10-23):

| Code | Next action |
| --- | --- |
| `BILLING_NOT_CONFIGURED`, `BILLING_WEBHOOK_NOT_CONFIGURED` | Set the Stripe server configuration and the signing secret for this exact webhook endpoint. `BILLING_NOT_CONFIGURED` also means that the Stripe key and the database have different modes (`test` or `live`). Nothing was sent to Stripe or saved. Ask the billing operator to check the mode of the key and of the database. |
| `ALREADY_SUBSCRIBED` | Open Account → Billing. Use **Change plan** to switch plans or **Cancel plan** to end the subscription. Do not create a second subscription. |
| `BILLING_CUSTOMER_MISSING` | Subscribe through the signed-in account before opening the portal. |
| `STRIPE_SIGNATURE_INVALID` | Send the original JSON bytes with a current Stripe signature. Check the endpoint's signing secret. |
| `EMAIL_WEBHOOK_NOT_CONFIGURED` | Configure the billing email endpoint signing secret and its matching Resend sender credential. Sending can remain disabled. |
| `EMAIL_SIGNATURE_INVALID`, `EMAIL_EVENT_INVALID` | Send the original provider event body with current Svix signature headers. Delivery evidence requires one recipient and a valid event time. Do not fabricate a delivery event. |
| `EMAIL_EVENT_CONFLICT` | The signed event identity conflicts with saved evidence. Delivery proof stays blocked; reconcile the exact event and sender namespace. Do not replace the event ID to bypass the conflict. |
| `RETENTION_PAYMENT_FENCED` | Retention review has stopped new Stripe request creation for this account. Read the existing request status. Do not retry with a new operation ID. Existing payment evidence must still be reconciled before the fence can be safely released. |
| `STRIPE_DISPATCH_COMPLETION_CONFLICT` | Keep the dispatch in reconciliation. Its completion reports conflict, and the first report cannot authorize cleanup. A known provider object or expired lease does not prove that the sender finished. |
| `STRIPE_DISPATCH_EXPIRED` | The original caller stopped before calling Stripe because its dispatch window ended. Read the existing request status; do not create a replacement payment automatically. |
| `STRIPE_ENVIRONMENT_MISMATCH` | Send events of the mode of this endpoint: test events to a test mode endpoint, live events to a live mode endpoint. Events of the other mode are refused. |
| `STRIPE_INVOICE_UNSUPPORTED`, `STRIPE_OBJECT_MISMATCH`, `STRIPE_PRICE_MISMATCH` | Ask the billing operator to inspect the parked event and Price mapping. Do not grant credits manually to bypass verification. |
| `STRIPE_UNAVAILABLE`, `BILLING_UNAVAILABLE`, `PAYMENT_PROCESSING`, `CUSTOMER_REVIEW_REQUIRED` | Refresh Billing before retrying. An operator must resolve an uncertain customer creation or a payment that remains pending. |
| `STRIPE_HISTORY_AMBIGUOUS`, `STRIPE_HISTORY_CHANGED`, `STRIPE_SUBSCRIPTION_CONFLICT` | Updated 2026-10-16: the worker retained evidence for review. Missing paid order, a changed immutable credit basis, or conflicting paid subscriptions cannot grant partial credits. An operator must resolve the history before retrying. |
| `STRIPE_TERM_UNSUPPORTED` | Updated 2026-10-16: inspect the verified paid term. Monthly terms over 31 days and annual terms over 366 days need supported provider evidence before scheduling. No partial schedule is applied. |
| `STRIPE_REFILL_INACTIVE` | Updated 2026-10-16: annual work is deferred while the subscription lacks active paid authority. The worker reads fresh provider evidence before retrying; it does not extend original credit expiry. |
| `CUSTOMER_CONFLICT`, `CHECKOUT_CHANGED`, `LEASE_LOST` | Read the current account or event state. Reuse the saved operation; do not start another payment to recover a lost response. |

Billing, access and uploads (2026-11-09):

| Code | Next action |
| --- | --- |
| `PUBLISH_NOT_ALLOWED` | This agent has no Publish authority. Ask the owner to select **Allow** in this agent's "Publish social posts" row in Agents. A publish tool returns an owner review in place of this code. `delete_post` and `cancel_post_schedule` return this code and change nothing. Do not retry until the owner allows it. |
| `YOUTUBE_NOT_CONNECTED` | Ask the owner to connect YouTube. Then read the post performance again. |
| `STORAGE_OBJECT_UNTRACKED` | Read the saved upload status. Do not start another transfer until the status is known. |
| `AUTH_IDENTITY_AMBIGUOUS` | This account cannot select a plan. The owner must contact support. Do not retry. |
| `CHECKOUT_BUSY` | Another Checkout start for this account is in progress. Wait, then read the billing status before you try again. |
| `CHECKOUT_INPUT_CHANGED` | The input differs from the saved request. Start again with a new request. Do not change the input of a saved request. |
| `PLAN_AUTHORIZATION_MISSING` | Billing has no saved authorization for this plan request. Refresh Billing. If the error stays, an operator must inspect the request. |
| `REFILL_CONSENT_REQUIRED` | The owner must set up automatic refill in Billing and accept its terms. |
| `REFILL_INELIGIBLE` | This account cannot use automatic refill now. Refresh Billing to see the plan state. |
| `REFILL_RECOVERY_REQUIRED` | An earlier refill is not finished. Read the billing status. An operator reviews the payment; do not start another refill. |
| `INTERNAL_BILLING_DISABLED` | An account on the internal plan cannot use Stripe billing. Do not retry. An operator must change the plan. |
| `STRIPE_PRICE_UNMAPPED` | Billing cannot match this Stripe price to a plan. Read the billing status. An operator must inspect the price mapping. Do not start another payment. |
| `CATALOGUE_MISSING` | Billing cannot find its base plan. Do not retry. An operator must restore the plan catalogue. |
| `RESERVATION_RELEASED` | The credit hold for this request was released before the result was saved. Read the saved request status. Do not repeat the paid request automatically. |
| `RESERVATION_UNKNOWN` | The result of this paid request is not known, and only an operator can release its credit hold. Read the saved request status. Do not repeat the paid request. |

| Kind                            | Next action                                                                                                                                                                                                                                     |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SIGN_IN_NOT_ACCEPTED`          | Check the email and password. Use **Send verification email** to verify the address. After HTTP 429, wait one minute. If the link does not arrive, contact the operator.                                                                        |
| `AUTH_REQUIRED`                 | Sign in again or renew the client's OAuth session. Use the token for this exact MCP resource.                                                                                                                                                   |
| `FORBIDDEN`                     | Ask the owner to check the account connection and workspace ownership at `/agent-access`. Agent credentials cannot perform owner-only actions.                                                                                                  |
| `ACCESS_ENDED`                  | Stop until the owner renews account access, or until the operator ends a suspension. Signing in again does not extend it. Renewal does not restore a disconnected agent.                                                                                                                 |
| Invalid input                   | Compare the call with the live tool schema in [Tool reference](/docs/reference/tools). Correct the field; a changed write intent needs a new request ID.                                                                                        |
| Conflict or changed content     | Read the current record and compare the owner's decision before making a new write. `CONTENT_CHANGED` means the post changed after review: read `get_post` and ask the owner to review again. Replay the original ID only with identical input. |
| `DELIVERY_NOT_COMPLETE`         | Record an observation only for a post with a completed delivery. Read `get_post` for its delivery status.                                                                                                                                       |
| Readiness blocker               | Fix the named condition in the owner UI and run a new exact-post check. A past pass can become stale.                                                                                                                                           |
| Storage or provider unavailable | Stop and tell the owner or operator. Read saved state before any retry; do not repeat a paid or publication operation with a new ID.                                                                                                            |
| Unknown or unconfirmed outcome  | Reconcile the saved job or operation. Never assume that the provider did nothing.                                                                                                                                                               |
| HTTP 429 `rate_limited`         | Stop. Wait for the seconds in the `Retry-After` header, fix the failing sign-in, then try again. See [Call the server](/docs/start/connect-hosted#call-the-server).                                                                             |

Updated 2026-10-28: the owner's **Publish to {n} platforms**, **Publish on X**, manual **Post** and **Schedule** send the review digest of the post that the owner sees. `CONTENT_CHANGED` (409) means that the post changed after the owner opened it, or that the page sent no digest (a page opened before this change). Nothing is approved, scheduled, sent or written. The page reads the post again: the owner checks it, then publishes again. After a refused **Schedule**, the owner selects **Reload saved post**, checks the post, then schedules again. An agent edit of the post after the owner looked causes this refusal. In **Publish to {n} platforms**, a version that moved to another channel stops Publish with `POST_CHANGED` (409): it counts as removed from the channel that the owner saw and added to the new channel. YouTube **Approve and upload** sends the YouTube settings that the owner confirmed. Different saved settings, or none, give the same refusal, and no upload is queued.

## Current code index

The list below is an index of literal error codes in the current server, SQL, and reference sidecars. Some codes only occur in owner or worker operations. A code in this list is not a promise that every MCP client can receive it. The runtime's safe message and the relevant workflow determine the next step.

### Advertising

`ADS_ADVERTISER_ALREADY_SELECTED`, `ADS_ADVERTISER_FORBIDDEN`, `ADS_ADVERTISER_SELECTION_REQUIRED`, `ADS_AI_DISCLOSURE_UNVERIFIED`, `ADS_APPROVAL_EXPIRED`, `ADS_APPROVAL_REVOKED`, `ADS_APP_CHANGED`, `ADS_AUTH_EXCHANGE_UNCONFIRMED`.

`ADS_AUTH_REQUIRED`, `ADS_AUTH_STATE_INVALID`, `ADS_CONNECTION_CHANGED`, `ADS_CONNECTION_NOT_FOUND`, `ADS_CONNECTION_ROLE_UNSAFE`, `ADS_CONNECTION_STORAGE_UNAVAILABLE`, `ADS_CREATION_ALREADY_RESERVED`, `ADS_ENTITY_NOT_FOUND`.

`ADS_EXECUTION_UNAVAILABLE`, `ADS_INVALID_RESPONSE`, `ADS_MANIFEST_CHANGED`, `ADS_MEDIA_CHANGED`, `ADS_OAUTH_NOT_CONFIGURED`, `ADS_OPERATION_NOT_FOUND`, `ADS_PLAN_BINDING_CHANGED`, `ADS_PLAN_NOT_FOUND`.

`ADS_PLAN_STORAGE_INVALID`, `ADS_PROVIDER_READINESS_REQUIRED`, `ADS_PROVIDER_REJECTED`, `ADS_QUEUE_BUSY`, `ADS_READINESS_NOT_FOUND`, `ADS_READ_UNAVAILABLE`, `ADS_REPORT_INCOMPLETE_DAY`, `ADS_REPORT_METADATA_REQUIRED`.

`ADS_REQUESTER_REVOKED`, `ADS_REQUEST_CONFLICT`, `ADS_RESPONSE_TOO_LARGE`, `ADS_REVIEW_CLOSED`, `ADS_REVIEW_EXPIRED`, `ADS_REVIEW_NOT_FOUND`, `ADS_SCHEDULE_PASSED`, `ADS_STALE_REVISION`.

`ADS_TIMEZONE_UNAVAILABLE`, `ADS_VAULT_UNAVAILABLE`.

### Instagram

For Dashboard post performance, reconnect Instagram after an authentication failure. An insights permission failure needs **Enable insights** or **Renew insights** in Connections. It does not end valid publishing access. A missing post keeps its last saved numbers. A refresh waits if another refresh is active. View totals include every available view count, including Instagram. A partial total or partial engagement count is labelled. The engagement rate uses only posts with available views and engagement counts; its label identifies partial inputs. Unsupported formats and insufficient provider data remain unavailable, not zero.

`INSTAGRAM_INSIGHTS_PERMISSION_REQUIRED`: authorize insights for the same connected account, then refresh. `INSTAGRAM_INSIGHTS_INSUFFICIENT_DATA`: Instagram has not supplied usable insights for this media; keep the previous snapshot. `INSTAGRAM_RATE_LIMITED`: wait before a new performance refresh. Do not publish again to repair a metrics failure.

`INSTAGRAM_REFRESH_FAILED`: the last token refresh failed and Instagram still accepts the saved token, so the connection stays connected. `INSTAGRAM_REFRESH_UNCERTAIN`: Instagram did not confirm the saved token; the owner must reconnect.

`INSTAGRAM_ACCESS_DENIED`, `INSTAGRAM_ACCOUNT_MISMATCH`, `INSTAGRAM_APPROVAL_REQUIRED`, `INSTAGRAM_CONNECTION_EXPIRED`, `INSTAGRAM_CONNECTION_STORAGE_UNAVAILABLE`, `INSTAGRAM_CONNECTION_UNCERTAIN`, `INSTAGRAM_CREDENTIAL_DATABASE_NOT_CONFIGURED`, `INSTAGRAM_CREDENTIAL_ROLE_UNSAFE`.

`INSTAGRAM_CREDENTIAL_STORAGE_UNAVAILABLE`, `INSTAGRAM_DESTINATION_UNAVAILABLE`, `INSTAGRAM_OAUTH_NOT_CONFIGURED`, `INSTAGRAM_PROVIDER_UNAVAILABLE`, `INSTAGRAM_PUBLICATION_CREDENTIAL_UNAVAILABLE`, `INSTAGRAM_PUBLICATION_NOT_CONFIGURED`, `INSTAGRAM_PUBLICATION_ROLE_UNSAFE`, `INSTAGRAM_PUBLICATION_STORAGE_UNAVAILABLE`.

`INSTAGRAM_QUOTA_EXHAUSTED`, `INSTAGRAM_READINESS_NOT_CONFIGURED`, `INSTAGRAM_RECONNECT_REQUIRED`, `INSTAGRAM_REEL_INSPECTION_UNAVAILABLE`, `INSTAGRAM_REEL_MEDIA_INVALID`, `INSTAGRAM_REFRESH_FAILED`, `INSTAGRAM_REFRESH_NOT_READY`, `INSTAGRAM_REFRESH_UNCERTAIN`, `INSTAGRAM_VAULT_NOT_CONFIGURED`.

`INSTAGRAM_VAULT_UNAVAILABLE`, `INSTAGRAM_VIDEO_REQUIRED`.

`INSTAGRAM_MEDIA_INVALID`: attach valid media for the selected format. `INSTAGRAM_STORY_ACCOUNT_UNSUPPORTED`: this app currently supports Stories from Business accounts. These errors do not authorize another provider submission.

### Facebook Pages

`FACEBOOK_NOT_CONFIGURED`, `FACEBOOK_VAULT_NOT_CONFIGURED`, `FACEBOOK_CREDENTIAL_ROLE_UNSAFE`: ask the operator to complete [Facebook setup](/docs/channels/facebook#operator-setup). `FACEBOOK_VAULT_UNAVAILABLE`, `FACEBOOK_CREDENTIAL_STORAGE_UNAVAILABLE`: read saved status and retry after storage recovery.

`FACEBOOK_RECONNECT_REQUIRED`: Facebook access ended or Facebook did not confirm it. Do not retry the call. Read `get_onboarding_status`. When the Facebook channel `state` is `reconnect-required`, give the owner its `connectUrl` and wait for the owner to connect again: the worker cannot refresh access that has ended. Updated 2026-11-19: an expired Facebook connection reads `reconnect-required`; before this date it read `connected`. See [Access lifetime and refresh](/docs/channels/facebook#access-lifetime-and-refresh). `FACEBOOK_PAGE_UNAVAILABLE`, `FACEBOOK_PAGE_REQUIRED`: connect again and select an eligible returned Page. `FACEBOOK_REQUEST_CLOSED`: open a new Connect request. `FACEBOOK_PROVIDER_UNAVAILABLE`: provider access or the result is unconfirmed; read saved status before retrying. `INVALID_FACEBOOK_STATE`: open the original owner connection link again; do not edit state.

`FACEBOOK_REEL_INSIGHTS_PERMISSION_REQUIRED`: Reel metrics are not available for this Page. No action is needed. Text/photo publishing and feed insights are not affected. A failed refresh keeps the previous successful metrics.

`FACEBOOK_MEDIA_INVALID`: replace the invalid photo/Reel export. `FACEBOOK_WORKER_ROLE_UNSAFE` and `FACEBOOK_WORKER_STORAGE_UNAVAILABLE`: ask the operator to restore the restricted worker setup. `FACEBOOK_PUBLICATION_STOPPED`: read the saved operation; an uncertain send must not be replaced. Changed content or destination needs a new exact review; a locked delivered post needs a new draft.

### Threads

`THREADS_NOT_CONFIGURED`, `THREADS_VAULT_NOT_CONFIGURED`, `THREADS_CREDENTIAL_ROLE_UNSAFE`: ask the operator to complete [Threads setup](/docs/channels/threads#operator-setup). `THREADS_VAULT_UNAVAILABLE`, `THREADS_CREDENTIAL_STORAGE_UNAVAILABLE`: wait for storage recovery and read saved status.

`THREADS_RECONNECT_REQUIRED`, `THREADS_PERMISSION_REQUIRED`: connect the same intended profile again and grant the required access. `THREADS_REFRESH_NOT_READY`: wait for the stored refresh time; token refresh cannot extend every data-access grant. `THREADS_REQUEST_CLOSED`: start a new owner request. `THREADS_PROVIDER_UNAVAILABLE`: access is unconfirmed; an unknown failure does not establish revocation. `INVALID_THREADS_STATE`: reopen the saved owner link without changing state.

`THREADS_MEDIA_INVALID`: choose a verified JPEG/PNG or supported video export and prepare a new review. `THREADS_PUBLICATION_STORAGE_UNAVAILABLE`: read saved status after storage recovery; keep the original approval request. `THREADS_QUOTA_REACHED`: wait for the provider quota before a new approval. `THREADS_CONTAINER_FAILED`: read the saved terminal result. `THREADS_PUBLICATION_UNKNOWN`: inspect the saved operation and native account; do not create another send.

For a durably saved final Threads post ID, the worker can repeat verification reads within the bounded recovery window. Reload reads saved status. An unknown write without that ID cannot be retried or reconstructed from caption/time. See [Threads publication](/docs/channels/threads#review-and-publish).

Internal erasure errors, added October 11, 2026: `META_ERASURE_ROLE_UNSAFE` requires the operator to restore the separate restricted lifecycle login. `META_ERASURE_STORAGE_UNAVAILABLE` requires storage recovery and a saved-operation read before another start. `META_ERASURE_BINDING_INVALID` means the saved owner/product/connection authority set does not match; do not broaden it by guessing. `META_ERASURE_CLAIM_STALE` requires a new worker claim for the same durable operation. These APIs have no owner/MCP entry point. Meta callbacks, added 2026-10-12, return `400` `INVALID_SIGNED_REQUEST` for any request that fails verification and make no database call. They return `503` `LIFECYCLE_NOT_CONFIGURED` when the product app settings are missing and `503` `LIFECYCLE_UNAVAILABLE` when storage fails. Meta can retry a `503`.

### Post performance

Updated 2026-11-19: `get_post_metrics` and `refresh_post_metrics` report a failed provider read in the `failure` field of each row, as `{ code, message }`. It is not a tool error. The row keeps the numbers of its last successful read, and the other rows are not affected. [Read post performance](/docs/workflows/metrics) lists the numbers of each channel.

`reconnect`: the saved connection of the channel is missing or lost. The owner reconnects the channel in Connections. Then call `refresh_post_metrics`. `NOT_RETURNED`: the channel did not return this post. Keep the earlier numbers; do not publish again. `PROVIDER_UNAVAILABLE`: the provider or the reader failed. Call `refresh_post_metrics` again later. Any other `failure.code` is the code of the channel, for example `INSTAGRAM_RATE_LIMITED`, `INSTAGRAM_INSIGHTS_PERMISSION_REQUIRED`, `FACEBOOK_REEL_INSIGHTS_PERMISSION_REQUIRED` or `THREADS_PERMISSION_REQUIRED`. Read the section of that channel in this page.

`refresh_post_metrics` can return `POST_METRICS_UNAVAILABLE` (409): ShipContent could not save the numbers. Call it again later. It returns `PLAN_SELECTION_REQUIRED` (403) when the owner has not selected a plan. `get_post_metrics` returns neither code. A call without live access to the workspace returns `FORBIDDEN`, and no provider is read.

### Publish permission

`YOUTUBE_QUOTA_EXCEEDED`: YouTube refused the upload because the API project's upload quota is used up. Nothing was uploaded and the job is `failed`. Publish again after the quota resets; do not retry at once.

`DESTINATION_UNAVAILABLE`: the selected account is unavailable in this workspace. Refresh the account list and choose a connected account. Updated 2026-11-19: `publish_post` and `prepare_post_schedule` also return it when the connected account of the post's channel cannot publish now, for example when its authorization ended. Give the owner the `connectUrl` of that channel from `get_onboarding_status`.

`DRAFT_CHANGED` (409): the post changed, or can no longer be edited, before the owner opened it in Studio. The owner saves the current draft first, then opens Studio again.

`PUBLISH_MODE_LOCKED`: the owner set this post to review. Keep it for owner review; only the owner can make it automatic.

`PUBLISH_IN_PROGRESS`: a delivery of the post started, or its result is not known, so the post cannot be deleted or archived now. `delete_post` and the owner **Delete** return it. Wait for the delivery result. Read `get_post`. Then try again.

`POST_PUBLISHED` (409): `delete_post` refused a published post. Only the owner can archive it. Archiving hides the post in ShipContent. It does not remove the post from the social network. Do not try again.

`DESTINATION_REQUIRED`: updated 2026-11-19. `publish_post`, `prepare_post_schedule` or `publish_instagram_reel` found no connected account for the post's channel, or the post names a different account. If no account is connected, give the owner the `connectUrl` of that channel from `get_onboarding_status`. If the post names a different account, the owner selects the account on the review page. `publish_instagram_reel` also returns it for a post that is not a Reel. Before this date, Facebook, Threads and YouTube reported a post without an account as a reconnect error.

`YOUTUBE_TITLE_REQUIRED`: added 2026-11-19 for `publish_post` and `prepare_post_schedule`. The YouTube post has no title. Save `youtube.title` with `edit_post`, then call again with a new `requestId`.

`PUBLISHING_UNAVAILABLE`: added 2026-11-19. `publish_post` has no publication path for the channel of this post. Read `get_post_catalogue`.

`READINESS_NOT_PASSED`: the check that `publish_instagram_reel` ran did not pass. Read `get_instagram_readiness`, fix the blocker, then use a new `requestId`.

`GRANT_NOT_ACTIVE`: the agent was disconnected. The owner must connect the client again at `/agent-access`.

`publish_off` is a result reason, not a tool error: the agent has no Publish permission. Publication and scheduling tools return `mode: "owner_review"`; give the returned review URL to the owner. A post with `reason: "post_requires_review"` still needs owner approval even with Publish.

### Agent image uploads

Updated 2026-11-19: a PUT to `directUpload.url` with `Content-Type: image/jpeg` or `image/png` returns `{ code, error }` with one of these codes. A refused image saves no asset and holds no budget. The upload returns to `pending` and takes the right file at the same URL. See [Upload an existing image](/docs/workflows/media#upload-an-existing-image).

| Code | Next action |
| --- | --- |
| `CONTENT_LENGTH_REQUIRED` (411) | Send `Content-Length` with the exact size of the file in bytes. |
| `UPLOAD_TOO_LARGE` (413) | The image is more than 30 MiB. Export a smaller image. |
| `MEDIA_TYPE_INVALID` (415) | `Content-Type` is another `image/` type, or the bytes are not a readable one-frame JPEG or PNG, or the image has more than 40,000,000 pixels. Send a JPEG or PNG that fits these rules. |
| `MEDIA_TYPE_MISMATCH` (415) | The bytes are a JPEG or a PNG, but not the type in `Content-Type`. Send the type that matches the file. |
| `MEDIA_UPLOAD_INCOMPLETE` (400) | The body has fewer bytes than `Content-Length`. Send the whole file again to the same URL. |
| `MEDIA_LIMIT_EXCEEDED` (413) | For an image upload: the body has more bytes than `Content-Length`. Send `Content-Length` equal to the file size. |
| `MEDIA_QUOTA_EXCEEDED` (409) | The file does not fit in the workspace media budget. Read `media.quota.availableBytes`, free space or send a smaller file. |
| `UPLOAD_URL_INVALID` (403) | The direct URL is not valid or it expired. Call `start_media_upload` again with the same `requestId` and label. |
| `UPLOAD_CLOSED` (409) | The upload is complete. Read `get_media_upload`. Do not send the file again. |
| `UPLOAD_MANIFEST_CONFLICT` (409) | The upload is bound to a different file. Start a new upload for the new file. |

### Media and uploads

`MEDIA_CHANGED`, `MEDIA_CONTENT_MISMATCH`, `MEDIA_DOWNLOAD_FAILED`, `MEDIA_INPUT_INVALID`, `MEDIA_LIMIT_EXCEEDED`, `MEDIA_OBJECT_EXISTS`, `MEDIA_PLAYBACK_BUSY`, `MEDIA_PUBLICATION_DEADLINE`.

`MEDIA_QUEUE_FULL`, `MEDIA_QUOTA_EXCEEDED`, `MEDIA_RENDER_FAILED`, `MEDIA_RENDER_INVALID`, `MEDIA_SOURCE_MISSING`, `MEDIA_STORAGE_NOT_CONFIGURED`, `MEDIA_STORAGE_UNAVAILABLE`, `MEDIA_TYPE_INVALID`, `MEDIA_TYPE_MISMATCH`.

`MEDIA_UNAVAILABLE`, `MEDIA_UPLOAD_BUSY`, `MEDIA_UPLOAD_INCOMPLETE`, `MEDIA_WORKER_ROLE_UNSAFE`, `MEDIA_WRITE_ABORTED`, `MEDIA_WRITE_UNCONFIRMED`, `STORAGE_MEDIA_CHANGED`, `STORAGE_MEDIA_NOT_FOUND`, `STORAGE_NOT_CONFIGURED`, `STORAGE_OBJECT_EXISTS`.

`STORAGE_PLAYBACK_BUSY`, `STORAGE_POLICY_REQUIRED`, `STORAGE_UNAVAILABLE`, `STORAGE_UPLOAD_UNCONFIRMED`, `UPLOAD_ABORTED`, `UPLOAD_BUSY`, `UPLOAD_CLAIM_INVALID`, `UPLOAD_CLEANUP_FAILED`.

`UPLOAD_CLOSED`, `UPLOAD_CONTENT_MISMATCH`, `UPLOAD_EXPIRED`, `UPLOAD_LIMIT_REACHED`, `UPLOAD_MANIFEST_CONFLICT`, `UPLOAD_MANIFEST_REQUIRED`, `UPLOAD_NOT_CONFIGURED`, `UPLOAD_READ_FAILED`.

Updated October 23, 2026: `MEDIA_WRITE_ABORTED` means the client closed its connection, and the write was cancelled before storage confirmed it. Upload the file again. `MEDIA_WRITE_UNCONFIRMED` still means that storage did not confirm the save.

Updated 2026-10-29: `MEDIA_RENDER_FAILED` also ends a native render after six failed attempts (errors or expired leases).

`UPLOAD_STATE_UNAVAILABLE`, `UPLOAD_STORED_MISMATCH`, `UPLOAD_TEMPORARY_UNAVAILABLE`, `UPLOAD_TIMEOUT`, `UPLOAD_TOO_LARGE`, `VIDEO_INSPECTION_FAILED`, `VIDEO_INVALID`.

### Authentication and access

For `EMAIL_VERIFICATION_REQUIRED`, open the verification email and then sign in. Sign in with the correct password to request a fresh link.

For `AUTH_EMAIL_UNAVAILABLE`, wait and request another email. The operator must check the Resend key and sender domain. Do not share reset or verification links with an agent.

`ACCESS_ENDED`, `AUTH_EMAIL_UNAVAILABLE`, `AUTH_NOT_CONFIGURED`, `AUTH_PROVIDER_UNAVAILABLE`, `AUTH_REQUIRED`, `AUTH_UNAVAILABLE`, `CLIENT_NOT_AUTHORIZED`, `CONSENT_UNCONFIRMED`, `CSRF_REQUIRED`, `FORBIDDEN`.

`GRANT_REQUEST_CLOSED`, `GRANT_REQUEST_EXPIRED`, `SIGN_IN_NOT_ACCEPTED`.

### Other

Updated 2026-10-17: a retained TikTok review reports `POST_NOT_FOUND` after its creative content is removed. Erased Instagram approval or readiness inputs can return `IDEMPOTENCY_CONFLICT` on replay. Read the saved request/status history; do not use a new request ID to recreate the removed operation. New generation for the removed post returns `DRAFT_CHANGED`. Start a separate draft only for new work. Retention cleanup remains disabled pending its activation checks.

`ACKNOWLEDGEMENT_CONFLICT`, `ALREADY_SIGNED_IN`, `ANALYSIS_INVALID`, `ANALYSIS_NOT_CONFIGURED`, `ANALYSIS_UNKNOWN`, `APPROVAL_MANIFEST_CHANGED`, `APPROVAL_REQUIRED`, `APPROVAL_STORAGE_UNAVAILABLE`.

`APP_NOT_READY`, `ASSET_NOT_FOUND`, `AUTHORITY_CHANGED`, `POST_NOT_FOUND`, `CHANNEL_IN_SET`, `CHANNEL_NOT_SUPPORTED`, `CHECK_CANCELLED`, `CHECK_UNAVAILABLE`, `CONNECTION_ACCOUNT_MISMATCH`, `CONNECTION_ALREADY_EXISTS`.

`CONNECTION_BUSY`, `CONNECTION_CLAIM_INVALID`, `CONNECTION_CLOSED`, `CONNECTION_EXPIRED`, `CONNECTION_LIMIT_REACHED`, `CONNECTION_NOT_CONNECTED`, `CONTENT_CHANGED`, `CREDENTIAL_UNAVAILABLE`, `CREDENTIAL_VERSION_CONFLICT`.

`DATABASE_NOT_CONFIGURED`, `DATABASE_ROLE_UNSAFE`, `DATABASE_UNAVAILABLE`, `DELIVERY_NOT_COMPLETE`, `DRAFT_LOCKED`, `FIRECRAWL_FAILED`, `FIRECRAWL_NOT_CONFIGURED`, `FOLLOW_UP_EVIDENCE_INVALID`, `IDEMPOTENCY_CONFLICT`.

`INPUT_CHANGED`, `INVALID_ANALYSIS_INPUT`, `INVALID_CALLBACK`, `INVALID_CONTENT_TYPE`, `INVALID_CONTEXT_FILE`, `INVALID_CURSOR`, `INVALID_INPUT`, `INVALID_INSTAGRAM_STATE`.

`INVALID_LIMIT`, `INVALID_PROJECT_SCOPE`, `INVALID_REQUEST`, `INVALID_STATE`, `INVALID_UPLOAD`, `INVALID_UPLOAD_ENCODING`, `INVALID_UPLOAD_LENGTH`, `INVALID_UPLOAD_LIMIT`.

`INVALID_UPLOAD_MANIFEST`, `INVALID_WEBSITE_FILE`, `INVALID_WEBSITE_URL`, `MARKETING_STORE_UNAVAILABLE`, `METHOD_NOT_ALLOWED`, `NOT_FOUND`, `OUTPUTS_INCOMPLETE`.

`OWNER_ORIGIN_NOT_CONFIGURED`, `POST_NOT_FOUND`, `READINESS_BUSY`.

`READINESS_CLAIM_INVALID`, `READINESS_LIMIT_REACHED`, `READINESS_REQUIRED`, `READINESS_STALE`, `READINESS_STORAGE_UNAVAILABLE`, `REQUEST_TIMEOUT`, `REQUEST_TOO_LARGE`, `RESULT_CHANGED`.

`REVIEW_UNAVAILABLE`, `SERVER_ERROR`, `SOURCE_CHANGED`, `STALE_CLAIM`, `STALE_REVISION`, `VERSION_NOT_FAILED`, `WEBSITE_BLOCKED`, `WEBSITE_FILE_CONFLICT`.

`WEBSITE_S3_NOT_CONFIGURED`, `WEBSITE_STORAGE_UNAVAILABLE`, `WEBSITE_WORKER_NOT_CONFIGURED`, `WEBSITE_WORKER_ROLE_UNSAFE`.

## Skill runs

Owner routes under `/api/skill-runs` start, read, list, answer and cancel a skill run. The workspace id is the `workspaceId` query. A file link at `/api/skill-run-files/{token}` streams the private bytes. It does not redirect. The service records the run and does not charge credits. The same request id with the same inputs returns the same run. A new run needs a new request id.

Updated 2026-11-05: An expired review stop rejects both approval and changes with `SKILL_RUN_STALE_ANSWER` until the expiry sweep closes the run. The sweep sets `NO_ANSWER_IN_TIME`.

| Code                        | Next action                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `SKILL_NOT_OPEN`            | Do not start this skill for this workspace.                                                                    |
| `SKILL_RUNS_UNAVAILABLE`    | Try again later. Do not start a replacement.                                                                   |
| `SKILL_RUN_INVALID_INPUT`   | Correct the named field. Use a new request id.                                                                 |
| `SKILL_RUN_CONFLICT`        | Read the existing run. A new run needs a new request id.                                                       |
| `SKILL_RUN_LIMIT`           | Finish or cancel an unfinished run, then use a new request id.                                                 |
| `SKILL_RUN_ALLOWANCE`       | Wait until `resetsAt`, then use a new request id.                                                              |
| `SKILL_RUN_SERVICE_CAP`     | Wait until `resetsAt`, then use a new request id.                                                              |
| `SKILL_RUN_NOT_FOUND`       | Read runs for this workspace only.                                                                             |
| `SKILL_RUN_STALE_ANSWER`    | Read the run. `detail` has the current preview, the recorded answer and who gave it. Do not answer again.      |
| `SKILL_RUN_NO_ROUNDS_LEFT`  | Approve the preview or cancel the run.                                                                         |
| `SKILL_RUN_FINISHED`        | Read the run. Do not answer or cancel again.                                                                   |

A failed run keeps `failure.code` and `failure.message`. Read that message. Do not start the same request again.

| Code                         | Next action                                                          |
| ---------------------------- | -------------------------------------------------------------------- |
| `RENDERER_UNAVAILABLE`       | Read the run. Try a new request later.                               |
| `RENDERER_STOPPED`           | Read the run. Do not start the same request again.                   |
| `STEP_TIMEOUT`               | Read the run. Do not start the same request again.                   |
| `OUTPUT_CHECK_FAILED`        | Read the run. Do not start the same request again.                   |
| `NETWORK_NOT_CLOSED`         | Read the run. Do not start the same request again.                   |
| `KIT_IMAGE_FAILED`           | Read the run. Do not start the same request again.                   |
| `KIT_VERSION_GONE`           | Read the run. Do not start the same request again.                   |
| `STEP_ENTRY_GONE`            | Read the run. Do not start the same request again.                   |
| `INPUT_DELETED`              | Read the run. Do not start the same request again.                   |
| `SANDBOX_CREDENTIAL_REFUSED` | Read the run. Do not start the same request again.                   |
| `SANDBOX_PAUSED`             | Read the run. Do not start the same request again.                   |
| `ACCESS_ENDED`               | Read the run. Stop until account access returns.                     |
| `NO_ANSWER_IN_TIME`          | Read the run. The stop closed with no answer.                        |
| `MEDIA_LIMIT_FULL`           | The run stays at its stop. Free storage, then approve again.         |

## YouTube errors

| Code                                     | Next action                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------------- |
| `YOUTUBE_NOT_CONFIGURED`                 | Ask the operator to configure the YouTube client.                               |
| `YOUTUBE_VIDEO_REQUIRED`                 | Attach one saved MP4 of at most 50 MiB.                                         |
| `YOUTUBE_CHANNEL_REQUIRED`               | Create a YouTube channel, then connect again, or choose another Google account. |
| `YOUTUBE_RECONNECT_REQUIRED`             | Reconnect YouTube and confirm the destination again.                            |
| `YOUTUBE_PROVIDER_UNAVAILABLE`           | Read saved status; do not create a replacement upload. YouTube gave no answer or a `5xx`; the worker tries again until the upload window closes. |
| `YOUTUBE_REQUEST_CLOSED`                 | Read the connection status and explicitly start a new request if needed.        |
| `YOUTUBE_ALREADY_CONNECTED`              | Use the saved channel or disconnect it before replacement.                      |
| `INVALID_YOUTUBE_STATE`                  | Open the owner connection page and start a new request.                         |
| `YOUTUBE_CREDENTIAL_STORAGE_UNAVAILABLE` | Ask the operator to check the restricted connection database.                   |
| `YOUTUBE_CREDENTIAL_ROLE_UNSAFE`         | Ask the operator to use the restricted connection login.                        |
| `YOUTUBE_VAULT_NOT_CONFIGURED`           | Ask the operator to configure the YouTube key ring.                             |
| `YOUTUBE_VAULT_UNAVAILABLE`              | Restore the matching key or reconnect after the operator resolves storage.      |

Updated 2026-11-19. These codes name how the worker ended a YouTube upload job. The worker saves the code in the audit and in the failure log. Two endings have no such record, because the job claim writes them: a start with no saved session (`failed`) and an upload window that closed before the start (`cancelled`). `get_youtube_status` returns the matching note and what YouTube said in `jobs[].error`. A job is `failed` only when YouTube holds no video of the upload. A job is `unknown` only when a video can exist. See [upload results](/docs/channels/youtube#upload-results).

| Code | Job | Next action |
| --- | --- | --- |
| `YOUTUBE_UPLOAD_REFUSED` | `failed` | YouTube refused the upload with a `4xx` answer. No video was published. Read `error`, fix the cause, then create a new post. A refused read of the session after the last byte went out is saved as `YOUTUBE_UPLOAD_UNCONFIRMED`. |
| `YOUTUBE_QUOTA_EXCEEDED` | `failed` | The upload quota is used up (`quotaExceeded` or `uploadLimitExceeded`). Nothing was uploaded. Publish again tomorrow. A quota answer to a read of the session after the last byte went out does not end the job: the worker reads the session again. |
| `YOUTUBE_UPLOAD_NOT_STARTED` | `failed` | YouTube did not start the upload, or the start has no saved session. No byte was sent. Create a new post. |
| `YOUTUBE_UPLOAD_INCOMPLETE` | `failed` | The session holds fewer bytes than the file and no more bytes will be sent, or YouTube no longer has the session and the last byte was never sent. No video was published. Create a new post. |
| `YOUTUBE_UPLOAD_UNCONFIRMED` | `unknown` | A video can exist and YouTube did not confirm it. The causes are: YouTube no longer has the session after the last byte went out, YouTube refused the read of the session, the channel changed after the upload started, or the result was not readable after the upload window closed. Check YouTube Studio. Do not upload again. |
| `YOUTUBE_CHANNEL_CHANGED` | `failed` | The channel of the saved token is not the approved channel, and no video exists: the upload did not start, or the last byte never went out. No more bytes are sent. When the last byte went out before the change, the job is `unknown` and the saved code is `YOUTUBE_UPLOAD_UNCONFIRMED`. Check the channel in YouTube Studio. |
| `MEDIA_CONTENT_MISMATCH` | `failed` | The saved video changed after approval. Nothing was uploaded. Create a new post with the current video. |

## X publishing errors

| Code                               | Next action                                                                                                                                                    |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X_UNAVAILABLE`                    | Read current X status. Reconnect if access changed; review the current revision or configuration before a new operation.                                       |
| `X_RECONNECT_REQUIRED`             | The owner reconnects X. A token refresh stopped before it finished, so the saved access can be spent.                                                          |
| `X_NOT_CONNECTED`                  | Dashboard post performance has no connection in status `connected`. Start `start_x_connection` and give the owner its `connectionUrl`.                         |
| `X_CREDENTIAL_STORAGE_UNAVAILABLE` | Read saved connection state before starting a replacement; the prior write may have committed.                                                                 |
| `X_CREDENTIAL_ROLE_UNSAFE`         | Configure a separate restricted X connection database login.                                                                                                   |

## Video errors

Updated 2026-11-09: `NOT_FOUND` (404) with the message `Video skills are not available.` means video skills are off for this owner. It comes from `GET /api/video-skills`, `list_video_skills`, `get_video_skill` and a plan request that has a `skill`. Do not retry with the same owner. The operator controls this list; see [video skills](/docs/workflows/videos#video-skills).

Updated 2026-10-25: the [technique search](/docs/workflows/videos#video-skills) browser read uses existing codes. `INVALID_INPUT` (400) requires correcting the request or its query encoding. Malformed percent escapes and invalid UTF-8 are rejected from the original HTTP query before Next.js normalizes it. Session, workspace access and the feature flag are checked before this input error. `NOT_FOUND` (404) means the search is disabled or an indexed entry is unavailable; it never selects a fallback result. An unauthenticated read remains 401 and a foreign-workspace read remains 403. Writes remain 405.

| Code                        | Next action                                                                                                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MOTION_RESULT_NOT_KEPT` | The provider completed the request, but its source changed or access ended before the result could be saved. The saved status reports whether credits were charged. Starting again creates a new request; the old request cannot restore the output. |
| `MOTION_APPROVAL_EXPIRED` | The unsubmitted AI approval expired or billing changed before submission. Check the saved request; review the current price before a new owner action. |
| `MOTION_CHANGED`            | The project changed after `expectedRevisionId`, or it is not ready. Read `get_project` and apply your change to `currentRevisionId`. In the editor, select **Discard my edits and load the latest version**. |
| `VOICEOVER_SCRIPT_CHANGED` | Updated 2026-11-19: another tab changed the first-cut voiceover script, or finished the voiceover, after this tab read it. Nothing was sent or charged. Reload the project and check the voiceover. |
| `MOTION_ASSET_KIND`         | Put an asset of the correct kind in the slot: a video for a clip, an image for an image scene or the logo, and audio or video for an audio track.                                       |
| `MOTION_RANGE_INVALID`      | Read `get_project` and choose a range that ends inside the saved video.                                                                                                                 |
| `MOTION_NOT_EXPORTED`       | Export this version, then download its files again.                                                                                                                                     |
| `MOTION_NOT_CONFIGURED`     | Ask the operator to check planning configuration. Updated 2026-11-07: a text-only video first cut can plan on fal Opus when `FAL_KEY` is set and `MOTION_OPUS_PLANNER_ENABLED` is exactly `true`, without `OPENAI_API_KEY`. A still format, a first cut with attached media, **Add a hook**, animation chat edits and **Ask AI** text proposals still need `OPENAI_API_KEY`. Without the required keys, planning returns this code before any reservation. |
| `MOTION_PLAN_FAILED`        | Change the brief, or fix the OpenAI account, before you start a new plan or hook. Updated 2026-11-08: when `error` says the planner reply was cut off at its length limit, the brief is not the cause. Keep the brief. A new plan is a new paid attempt, so start one only when the owner accepts that charge. |
| `MOTION_PLAN_UNKNOWN`       | Keep the original request IDs and read the saved draft. Browser planning can return this code with HTTP 403 if access ends after acceptance. Restore access, then check or replay the same request; do not start another paid attempt automatically.                                                                                                          |
| `MOTION_SCENE_FAILED`       | Check the OpenAI account and the instruction, then send the instruction again.                                                                                                          |
| `MOTION_SCENE_INVALID`      | Change the animation instruction and try again. The scene did not change.                                                                                                               |
| `MOTION_SCENE_UNKNOWN`      | The paid animation request has no known outcome, and the scene did not change. Decide before you send a new request.                                                                    |
| `MOTION_TEMPLATE_LIMIT`     | Delete a saved template, then save the new one. A workspace keeps 30.                                                                                                                   |
| `TRANSCRIPT_NOT_CONFIGURED` | Ask the operator to configure the server ElevenLabs key for transcription.                                                                                                             |

### ElevenLabs owner account

Updated 2026-11-10: these codes come only from the owner Settings card and the owner Studio voice picker. An agent cannot connect an ElevenLabs account or pick an owner account voice. ShipContent never creates, clones, designs, uploads or changes a voice.

| Code | Next action |
| --- | --- |
| `ELEVENLABS_KEY_REJECTED` | ElevenLabs refused the key. The owner checks that the key is active and can read voices, then connects again in Settings. Nothing was saved. After a refused refresh, the account needs a reconnect. |
| `ELEVENLABS_UNAVAILABLE` | ElevenLabs did not answer. Try again later. Nothing was saved. |
| `ELEVENLABS_NOT_CONNECTED` | No working ElevenLabs account is connected to this workspace. Connect it in Settings. |
| `ELEVENLABS_INPUT_INVALID` | Reload Settings and send the request again. |
| `ELEVENLABS_VOICE_UNAVAILABLE` | The voice is no longer in the connected account. Refresh the voices in Settings, or pick another voice. No job was made. A retry with the same request ID and inputs returns the saved job, even after the voice left the account. |
| `ELEVENLABS_VAULT_NOT_CONFIGURED`, `ELEVENLABS_VAULT_UNAVAILABLE`, `ELEVENLABS_STORAGE_UNAVAILABLE`, `ELEVENLABS_STORAGE_ROLE_UNSAFE` | The operator must check the separate database login and the ElevenLabs vault settings. The built-in voices still work. |

A voiceover with an owner account voice that ElevenLabs refuses fails with `MEDIA_PROVIDER_REJECTED`. Its credit hold is released. Updated 2026-11-12: a 401 marks the account reconnect-required only when the reply is not a spent quota (`quota_exceeded`) and the key that made the request is still the saved key. A spent quota leaves the account connected. A key saved after that request started stays connected with its voices. The job never moves to the ShipContent key.

## Cross-posting errors

A refusal from `cross_post` makes no drafts. The error has `refused`: each refused channel with its code.

| Code                    | Next action                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `CHANNEL_NOT_SUPPORTED` | The post's format does not publish on that channel today. Remove the channel.                                |
| `CHANNEL_IN_SET`        | The channel already has a version that is not failed. Read `get_post` `set` and work on that version.        |
| `VERSION_NOT_FAILED`    | The channel's version has an unknown result. Do not retry. Give the owner `review.url` to check the channel. |

## Scheduling errors

| Code                                        | Next action                                                                                                             |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `SCHEDULING_UNAVAILABLE`                    | Keep a planned draft. This publishing operation is Coming soon.                                                         |
| `SCHEDULE_DISPATCH_STARTED`                 | Read `get_post_schedule` and delivery state. For TikTok, read `get_tiktok_status`. Sending started; `cancel_post_schedule` and the owner cancel did not stop the provider job. |
| `SCHEDULE_OWNER_LOCKED`                     | The owner made this schedule or TikTok operation. `cancel_post_schedule` and `delete_post` leave it as it is. Tell the owner: only the owner can cancel it or delete the post. |
| `SCHEDULE_LATE`                             | Read the blocked schedule. Confirm a new future schedule explicitly; do not replay it as new provider work.             |
| `SCHEDULE_AUTHORITY_CHANGED`                | Read the saved schedule and current account/access. The owner must review before new authority.                         |
| `X_NOT_CONFIGURED`                          | Ask the operator to configure the X client. Reconnect does not fix missing server configuration.                        |
| `FACEBOOK_NOT_CONFIGURED`                   | Ask the operator to configure Facebook. Reconnect does not fix missing server configuration.                            |
| `THREADS_NOT_CONFIGURED`                    | Ask the operator to configure Threads. Reconnect does not fix missing server configuration.                             |
| `INSTAGRAM_NOT_CONFIGURED`                  | Ask the operator to complete Instagram configuration.                                                                   |

Missing client/vault configuration is a definite new-dispatch blocker even when its HTTP status is 503. It needs operator action, not a repeated retry. Linked jobs retain recovery. `CONTENT_CHANGED` requires reload and new confirmation. `CSRF_REQUIRED` requires reload while keeping the same confirmed request. An unknown result requires a saved-state read before any retry.

### TikTok Accounts

`TIKTOK_REQUEST_CLOSED` means the saved sign-in request ended. Open Connect again. `TIKTOK_ACCOUNTS_VAULT_NOT_CONFIGURED`, `TIKTOK_ACCOUNTS_VAULT_UNAVAILABLE`, `TIKTOK_ACCOUNTS_CREDENTIAL_ROLE_UNSAFE` and `TIKTOK_ACCOUNTS_CREDENTIAL_STORAGE_UNAVAILABLE` require the operator to check the separate database login and encryption settings.

`TIKTOK_NOT_CONFIGURED`: the operator must configure the portal-generated account-holder authorization URL and exact HTTPS callback.

`TIKTOK_PERMISSION_REQUIRED`: the account has not granted the operation permission. Check Accounts access and reconnect after approval.

`TIKTOK_RECONNECT_REQUIRED`: reconnect the customer account. An advertiser token cannot replace its authorization.

`TIKTOK_RATE_LIMITED`: wait for the provider allowance to recover, then read saved status before another action.

`TIKTOK_PROVIDER_UNAVAILABLE`: read the saved operation. An unconfirmed publication or reply must not be submitted again automatically. When a prepare call returns this error, no review is saved: repeat the same request after the outage.

`TIKTOK_REVIEW_CHANGED`, `TIKTOK_REVIEW_UNAVAILABLE`: prepare the current saved video again before owner approval.

`TIKTOK_VIDEO_REQUIRED`, `TIKTOK_VIDEO_INVALID`: select one compatible saved MP4 and set all six TikTok settings.

`TIKTOK_PUBLIC_ACCOUNT_REQUIRED`: enable public posts in the TikTok account, then prepare again.

`TIKTOK_SETTINGS_CHANGED`: set the post interaction flags to match the current account restrictions.

`TIKTOK_SCHEDULE_PASSED`: duplicate a locked post, select a new UTC time and prepare again.

`TIKTOK_MEDIA_NOT_CONFIGURED`: the operator must configure an owned HTTPS media origin and verify it with TikTok.

`TIKTOK_MEDIA_NOT_VERIFIED`: the operator must verify a URL property that covers the exact video retrieval URL for this developer app.

`TIKTOK_PUBLICATION_REJECTED`: check the video in TikTok, fix the rejection, then duplicate the post to prepare it again.

`TIKTOK_REPLY_TARGET_UNAVAILABLE`: refresh the owned video and comments. Select a public parent comment before preparing a reply.

`TIKTOK_REPLY_UNKNOWN`: check TikTok and the saved receipt. A lost reply response must not trigger another send.

`TIKTOK_PAGINATION_STOPPED`: TikTok repeated a cursor, or the bounded scan ended. Refresh the list to start again. The list is incomplete.

`TIKTOK_PUBLICATION_UNKNOWN`: read the saved receipt and check TikTok. Do not submit the same video again to repair a lost response.

`TIKTOK_INSIGHTS_UNAVAILABLE`: select an owned organic video or a supported UTC period, then refresh. The previous successful snapshot stays available.

Updated October 11, 2026: `META_ERASURE_STATUS_UNAVAILABLE` is a sanitized internal read failure. The public deletion-status page shows the same unavailable page for this failure, unknown links and expired links. The operator must check the app-only `SHIPCONTENT_META_STATUS_DATABASE_URL` and restricted status role; do not use another domain credential.

## Credit and plan failures

Updated 2026-10-24: `PLAN_SELECTION_REQUIRED` (403) means the owner must choose a plan before new work. Give the owner the trusted `upgradeUrl` when present; it opens the numbered Plans page and does not grant access. `FREE_UNAVAILABLE` (409) means this account already used Free; choose Pro. Updated 2026-11-02: `FREE_ALREADY_USED` (409) means this email already used Free on another account; choose Pro. `CHECKOUT_RECOVERY_REQUIRED` (409) means an earlier payment request needs status recovery before another selection. `EMAIL_UNVERIFIED` (403) means the owner must verify email before starting Free. `FREE_CATALOGUE_UNAVAILABLE` and `FREE_CATALOGUE_INVALID` (503) mean Free cannot start until the published catalogue is available. `PLAN_ALREADY_ACTIVE` (409) means refresh selection and read the saved account plan. A canceled Checkout or browser return does not prove payment.

Updated 2026-10-16. `PRICE_CHANGED` returns HTTP 409: read the current price before a new submission. If a zero-credit Motion approval becomes paid before provider submission, the request stops for a new owner approval; it does not reserve the new price silently. `INSUFFICIENT_CREDITS` returns HTTP 402: ask the owner to check Billing. `PLAN_LIMIT_REACHED` returns HTTP 403: ask the owner to check the named limit.

An action quote uses the immutable decimal price version for that action. A change to another action does not invalidate it. A paid action needs a matching quote before a new credit hold. A zero-credit action still requires `ai.enabled`. A replay with an existing hold uses its saved quote and original billing mode.

`INSUFFICIENT_CREDITS` includes `required`, `available`, `planBalance`, `purchasedBalance` and the trusted recovery URL. The two split balances count spendable credits: unexpired, unfrozen remaining credits minus reserved credits. Other grant kinds can make `available` larger than these two splits. `PLAN_LIMIT_REACHED` also includes the recovery URL.

These failures can include `actionKey`, `required`, `available`, `planBalance`, `purchasedBalance`, `priceVersion`, `limitKey`, `limit`, `used`, `resetsAt`, and `upgradeUrl`. Credit amounts can be decimal strings to preserve exact large values. A null `limit` has no numeric cap; `resetsAt` is an ISO timestamp. Updated 2026-10-24: `upgradeUrl`, when present, is a trusted owner recovery path: `/workspaces`, a numbered Billing page, or a numbered Plans page. Opening that URL does not grant access or change a plan.

Updated 2026-10-17: explicit unlimited-credit authority prevents insufficient-credit refusals, but it does not bypass quote approval or account access checks. The operator-only unlimited-credit setting returns `INTERNAL_PLAN_REQUIRED` unless the account has an effective internal assignment. Owners and agents cannot set this policy.

Updated 2026-10-17: billing email workers can return `NOTICE_LEASE_LOST`, `NOTICE_SUPPRESSED`, `RECIPIENT_UNAVAILABLE`, `NOTICE_PAYLOAD_CONFLICT`, `NOTICE_SENDER_CHANGED`, `SENDER_UNRESOLVED`, `RECIPIENT_CHANGED` or `DELIVERY_RECOVERY_REQUIRED`. These are internal delivery diagnostics, not owner or agent spending errors. Do not create a replacement delivery key for an uncertain send. A stale claim or an expired provider retry window does not prove that no email was accepted.

## Media accounting recovery

Updated 2026-10-16. `MEDIA_SUBMISSION_STARTED` (409) means provider submission or native render execution has started. Keep the saved job; cancellation cannot release its credits. `MEDIA_DURATION_REQUIRED` means an automatic-duration video succeeded but its duration has not been inspected. Its hold stays reserved until inspection or operator reconciliation. Do not generate a replacement to repair the download. `PRICE_CHANGED` requires refreshing the displayed quote and another owner approval.


Updated 2026-11-07: `MEDIA_APPROVAL_EXPIRED` means the one-hour unstarted approval expired. This includes spending budget holds in shadow mode; a worker cannot create a replacement hold. `MEDIA_APPROVAL_REQUIRED` means billing mode changed before execution. Both leave the job awaiting a new owner decision on the current quote. They do not mean the price changed and do not extend the expired hold.

`MEDIA_PROVIDER_RESULT_INVALID`, `MEDIA_CONTENT_MISMATCH`, `MEDIA_TYPE_INVALID` and `MEDIA_LIMIT_EXCEEDED` can finish file collection as failed after provider success. Successful fixed-quantity work stays charged. Automatic-duration work without a trusted measurement retains its hold for operator reconciliation.

`MEDIA_COLLECTION_RECONCILIATION_REQUIRED` means temporary collection failures exhausted six attempts with increasing delays. `MEDIA_PRICE_RECONCILIATION_REQUIRED` means the exact price row for an actual priced reservation is unavailable. An optional off-mode quote with no reservation does not require this row. Stop automatic recovery and ask the operator to inspect the saved evidence. Do not release the hold or use a current price as a replacement.

`MEDIA_OUTCOME_RECONCILIATION_REQUIRED` means receipt recovery exhausted six attempts. `MEDIA_PROVIDER_RECEIPT_NOT_FOUND` records a 404 read; it does not prove that the provider did no work. `MEDIA_OUTCOME_READ_FAILED` and `MEDIA_PROVIDER_PENDING` record an unsuccessful read or an unfinished provider result. Unknown holds stay reserved for operator evidence. Restoring membership or moving an unresolved job back to the normal queue does not reset its receipt-recovery budget or unpark it. Outcome-only recovery never submits or transfers media files.

Updated 2026-10-16: after a confirmed receipt outcome, an active authorized job is scheduled for collection or finishes as failed. A cancelled or failed job is not revived. If source authority is gone, automatic-duration success without inspection keeps its unknown hold for operator evidence. Recovery scheduling survives a worker stop between outcome recording and lease release.


Updated 2026-10-16: website actions can return `WEBSITE_APPROVAL_REQUIRED` or `WEBSITE_APPROVAL_EXPIRED`. Read the current sources and prices, then start a new owner action. `WEBSITE_OUTCOME_UNKNOWN` means the submitted request is kept without an automatic retry. `PRICE_CHANGED`, `PLAN_LIMIT_REACHED` and `INSUFFICIENT_CREDITS` retain their validated billing details on website requests.

Updated 2026-10-23: `WEBSITE_APPROVAL_EXPIRED` applies only when the action holds credits and the hold has ended. With billing off or a zero-credit action, a queued website action does not expire. `WEBSITE_APPROVAL_REQUIRED` is returned with billing shadow or enforce when no approval was saved; with billing off, an older queued action still runs.

Updated 2026-10-23: `MOTION_APPROVAL_EXPIRED` on AI planning, editor edits, transcripts and caption suggestions applies only when the request holds credits and the hold has ended. With billing off, or for a zero-credit request, a prepared request does not expire. Switching billing to enforce still refuses an approval that was saved with billing off.

Updated 2026-10-16: owner plan changes can return `PLAN_RECOVERY_REQUIRED` when a prior send has an uncertain result. Use **Check plan request**; do not start a new payment to bypass it. `PLAN_CONFIGURATION_MISSING`, `PLAN_CONFIGURATION_CHANGED` and `PLAN_CONFIGURATION_MISMATCH` require verified catalogue or Portal setup. `PLAN_INPUT_CHANGED` requires the original selection for that request. `PLAN_PAYMENT_REQUIRED` directs the owner to complete the existing invoice. `PLAN_CHANGE_CONFLICT`, `SCHEDULE_CONFLICT` and `SCHEDULE_SETTINGS_UNSUPPORTED` require review of the current subscription or schedule before another change. `PLAN_PAYMENT_METHOD_UNSUPPORTED` requires an owned supported card or Link method for a pending allowance upgrade. These are owner-only actions; agents cannot submit them.

Updated 2026-10-16: the sandbox catalogue CLI uses `CATALOG_INPUT_CHANGED` for changed immutable operation input; reuse the original operation file, actor and reason. `CATALOG_RECOVERY_REQUIRED` retains unknown remote work and blocks competing catalogue writes. Read the same operation; do not choose a new key. `CATALOG_FENCE_LOST` stops an expired or revoked send authorization. `CATALOG_BASELINE_CHANGED` and `CATALOG_REMOTE_DRIFT` require review of changed local or provider state. `CATALOG_ENVIRONMENT_MISMATCH`, `CATALOG_PRODUCT_MISMATCH`, `CATALOG_LOOKUP_CONFLICT` and `CATALOG_TAX_CONFLICT` refuse inconsistent catalogue identity or terms. `CATALOG_CONFIGURATION_MISSING`, `CATALOG_CONFIGURATION_CONFLICT`, `CATALOG_CONFIGURATION_MISMATCH` and `CATALOG_CONFIGURATION_DRIFT` require verified Portal setup without removing unrelated settings. Updated 2026-10-23: `CATALOG_ENVIRONMENT_MISMATCH` also means that the Stripe key, the `--remote` value (`sandbox` or `live`) and the Stripe mode of the database are not the same mode. Nothing was sent to Stripe. These are restricted operator operations, not owner or agent purchase actions.

Updated 2026-10-16: `CATALOG_CONFIGURATION_INCOMPLETE` means an expanded Portal read still omitted its product array; stop without assuming an empty selection. `CATALOG_CORRECTION_UNAVAILABLE` means the requested quantity-only correction is outside its known partial-clone scope or is already prepared; inspect the same operation. `CATALOG_CORRECTION_SELECTION_CHANGED` requires the exact saved correction preview and reason; do not overwrite a changed current configuration. This explicit operator child keeps its own one-shot authorization. Ordinary resume never starts a corrective mutation.

Updated 2026-10-16. X approval, final X publication and automatic schedule admission can return `PLAN_LIMIT_REACHED` with HTTP 403 and the same validated billing details. Read `limitKey`; check Billing before a new action. A refused schedule time change preserves the original schedule. Read saved publication results after a plan change; do not retry an unknown provider write.

Updated 2026-10-16: `PLAN_LIMIT_REACHED` also applies to new workspaces, final channel connection saves, upload reservations and positive asset storage additions in enforce mode. Read the safe `limitKey`, `limit` and `used` details. Reduce usage or ask the owner to change the plan before a new increase. A failed asset save does not grant permission to repeat generation or a provider submission. Existing files can be deleted or shrunk above a downgraded cap.

Updated 2026-10-17: Browser and MCP billing failures preserve validated `required`, `available`, `planBalance`, `purchasedBalance`, `priceVersion`, `limitKey`, `limit`, `used`, `resetsAt` and `upgradeUrl` fields where present. Keep large amounts as decimal strings. The shortfall is exact integer subtraction, clamped at zero. Recovery links use an owner-derived numbered Billing path or `/workspaces`; an owner page guard checks access again. Untrusted URLs and provider details are discarded. `PRICE_CHANGED` requires a new explicit owner action after the visible quote refreshes.

Updated 2026-10-17: for Library owner uploads and owner/direct MP4 uploads, `STORAGE_OPERATION_UNRESOLVED` means the original write or rollback still needs a confirmed result. Keep the same upload ID and read its status; do not send a replacement upload to bypass it. `STORAGE_FENCED` pauses new storage work during retention checks. `STORAGE_LEGACY_UNRESOLVED` needs operator reconciliation of an older attempt. `STORAGE_KEY_RETIRED` refuses reuse of a previous storage destination. `STORAGE_PROTOCOL_REQUIRED`, `STORAGE_AUTHORITY_UNAVAILABLE` and `MEDIA_STORAGE_NAMESPACE_CHANGED` require operator review before another transfer. `STORAGE_RECEIPT_INVALID` and `STORAGE_OUTCOME_CONFLICT` do not authorize another storage request.


Updated 2026-10-17: generation, voiceover and render recovery can report `STORAGE_NAMESPACE_MISMATCH` when recovery points to a different storage destination, `STORAGE_CONTENT_MISMATCH` when stored bytes differ from the reserved output, or `OUTPUT_ALREADY_SAVED` when the output already has its asset. `STORAGE_FENCED` stops new writes and asset saving; confirmed provider charges remain valid. `STORAGE_LEGACY_UNRESOLVED` needs operator review of an older writer. Keep the same job ID. These errors never authorize a replacement generation.


Updated 2026-10-17: website evidence and imported image saves also use `STORAGE_FENCED`, `STORAGE_NAMESPACE_MISMATCH`, `STORAGE_GENERATION_CHANGED` and `STORAGE_OPERATION_UNRESOLVED`. Keep the same import/file or asset identity for recovery. `WEBSITE_FILE_CONFLICT` refuses different bytes for that identity. A failed storage response does not authorize another capture or generation.

Updated 2026-10-17: `PLAN_REQUEST_REQUIRED` also rejects the retired direct Customer-binding action. Customer setup must use the saved owner request and its original dispatch identity. Recover that request after an uncertain response; do not attach an arbitrary Customer ID.

Updated 2026-10-17: retention workers record `GRAPH_ATTESTATION_REQUIRED`, `NATIVE_CREATION_UNRESOLVED`, `PROVIDER_HISTORY_REQUIRES_REVIEW` or `EXTERNAL_ROOT_CONTROLS_REQUIRED` when payment closure is unproved. A stored certificate with changed evidence is also unusable. These are internal preservation diagnostics; they do not authorize a payment retry or file deletion.

Updated 2026-10-17: a valid contradictory storage receipt is retained before `STORAGE_OUTCOME_CONFLICT` is returned. It blocks new storage authority and drain; repeating the old receipt does not clear it. Retention preparation stops at `PHYSICAL_NAMESPACE_PROOF_REQUIRED` after capturing tracked objects. That state does not authorize deletion.

Updated 2026-10-17: physical retention inspection rejects unsupported bucket versioning (`RETENTION_STORAGE_VERSIONING_UNSUPPORTED`), invalid responses (`RETENTION_STORAGE_RESPONSE_INVALID`), untracked keys (`UNTRACKED_PHYSICAL_OBJECT`), missing expected objects (`PHYSICAL_OBJECT_MISSING`), changed content (`PHYSICAL_STATE_CONTRADICTED`) and pending multipart uploads (`STORAGE_MULTIPART_UNRESOLVED`). `STORAGE_SCAN_READ_FAILED` retains the same scan cursor for a bounded retry. `RETENTION_STORAGE_CURSOR_INVALID` means a multipart marker pair is malformed or repeats; `RETENTION_STORAGE_PAGE_INVALID` includes an oversized or invalid page. `PHYSICAL_MULTIPART_PROOF_REQUIRED` rejects earlier prefix-only evidence. Keep the existing run blocked and review the original evidence. A successful scan stops at `STORAGE_RUNTIME_PROOF_REQUIRED`. These internal diagnostics do not authorize deletion; cleanup remains disabled.

Updated 2026-10-18: retention storage preparation returns `STORAGE_OPERATION_UNRESOLVED` before installing a new storage fence when an original sender remains unresolved. Operator cancellation can return `pending_drain`; keep its operation ID and original arguments until storage outcomes are reconciled. A canceled existing run with only unresolved PUTs releases payment access while retaining storage holds. Unresolved or conflicting DELETEs retain payment protection. `RETENTION_OPERATION_CONFLICT` identifies an existing cancellation. `RETENTION_CANCEL_REQUIRED` and `RETENTION_DRAIN_REQUIRED` prevent a new warning before cancellation finishes. `RETENTION_RUN_SUPERSEDED` requires review of the latest run, and `RETENTION_NOT_ELIGIBLE` preserves current access or payment protection. These operations are unavailable to app and agent credentials and do not enable deletion.

Updated 2026-10-17: an operator internal-access request can return `pending` while an earlier retention DELETE remains unresolved. `INTERNAL_ASSIGNMENT_CONFLICT` returns the existing request ID; use that request's status or retry action. Exact replay cannot extend its absolute expiry. `expired`, `withdrawn` and `superseded` are terminal outcomes, not effective grants. `INTERNAL_ASSIGNMENT_TERMINAL` rejects withdrawal of a different completed outcome. `INTERNAL_ASSIGNMENT_PENDING` and `RETENTION_DELETE_FENCED` prevent new deletion authority. No app or agent credential can invoke these operator actions.

Updated 2026-10-17: `RETENTION_DELETE_UNKNOWN` and `RETENTION_DELETE_RECEIPT_UNCONFIRMED` require reconciliation of the original deletion operation. Do not retry the storage DELETE. `RETENTION_DELETE_EXPIRED` or `RETENTION_DELETE_NOT_SENT` does not grant a replacement send. `RETENTION_DELETE_RETRY_CONFIGURATION` rejects an SDK configuration that permits native retries. `RETENTION_CONTENT_CLEANUP_REQUIRED` identifies remaining content work, not completed account cleanup. Cleanup remains disabled pending runtime and provider acceptance.

Updated 2026-10-17: `RETENTION_DISABLED` means cleanup is paused. `RETENTION_STORAGE_NAMESPACE_CHANGED` or `RETENTION_STORAGE_SCOPE_INVALID` stops a deletion before its native call when the configured storage target or workspace key does not match the captured authority. Preserve the original operation and review its configuration; do not substitute another bucket or key.

Updated 2026-10-17: internal content checks preserve posts with `POST_SCHEDULE_BINDING_REQUIRED`, `POST_CONTENT_CHANGED`, `POST_SCHEDULE_HISTORY_CHANGED`, `POST_OUTSIDE_CAPTURED_SCOPE`, `POST_PUBLICATION_HISTORY_PROTECTED` or `POST_GENERATION_UNRESOLVED`. A cancellation must match the original Free period. These are preservation diagnostics, not permission to erase content; cleanup remains disabled.

Updated 2026-10-17: retention quota recovery stops on `RETENTION_FILE_IDENTITY_CONFLICT`, `RETENTION_FILE_ACCOUNTING_CONFLICT` or `RETENTION_FILE_ACCOUNTING_UNDERFLOW`. `RETENTION_DELETE_REQUIRED` and `RETENTION_OBJECT_DELETION_INCOMPLETE` mean the original successful deletion evidence is missing. Preserve the operation and refer its saved evidence to an operator; do not retry a storage DELETE or adjust quota from object absence.

Updated 2026-10-17: Media and Motion can return `STORAGE_KEY_RETIRED` before new authorization or first submission when retention deletion of an input file is confirmed, pending or contradictory. Select another source for a new request; preserve the identity of any request already submitted. A refusal rolls back its new job, projection and reservation.

Updated 2026-10-17: schedule creation and channel upload/staging can also return `STORAGE_KEY_RETIRED`. Use another file for a new request. Keep an existing submitted request and its saved provider identity for recovery; a source refusal does not authorize another upload or publication.

Updated 2026-10-17: website file access, saved-file reuse and analysis can return `STORAGE_KEY_RETIRED`. Remove or replace the unavailable current source through a new owner action. Do not retry the old file PUT under a different key. Existing submitted provider requests retain their original recovery identity.

Updated 2026-10-17: internal file completion stops on `RETENTION_FILE_SCOPE_INCOMPLETE`, `RETENTION_FILE_PROGRESS_CONFLICT` or `RETENTION_FILE_MATERIALIZATION_CONFLICT`. `RETENTION_FILE_ACCOUNTING_REQUIRED` identifies missing original quota evidence; the saved file step can reconcile it without another DELETE. `RETENTION_FILE_CURSOR_CHANGED` retries the current captured scope. Review the original rows and receipts; do not replace an old key, invent absence evidence or mark the account purged.

Updated 2026-10-17: saved-output recovery can return `STORAGE_KEY_RETIRED` before object reads or materialization. A completed owner upload with no current `asset` uses the same code in the client; its original upload is still complete. Do not retry that transfer to restore the file. A deliberate new upload is a separate owner action. Keep original provider and storage receipt IDs for reconciliation.

Updated 2026-10-17: internal `RECONCILIATION_LEASE_LOST` or `RECONCILIATION_ACCOUNT_MISSING` stops a local accounting step without advancing its cursor. The saved run remains incomplete until its bounded work succeeds. These diagnostics do not authorize a new payment, ledger adjustment or unknown-hold release.

Updated 2026-10-17: internal provider reconciliation can park as `RECONCILIATION_SCOPE_MISMATCH` when the returned Customer, account, root or period differs from the saved daily target. Keep the original work ID and inspect the binding. It does not authorize a replacement payment, credit grant or customer reassignment. App and agent credentials cannot override the check.

Updated 2026-10-17: `RECONCILIATION_WORK_MISSING` stops an internal unattributed-event check when its saved queue row is unavailable. The cursor does not advance. `RECONCILIATION_LEASE_LOST` also protects this scan; the worker must acquire a fresh claim. App and agent credentials cannot run these controls or assign an event to an account.

Updated 2026-10-17: `BILLING_OPERATOR_INVALID_INPUT` requires a valid saved operation file and supported flags. `BILLING_OPERATOR_INPUT_CHANGED` rejects changed intent under a saved operator UUID. `BILLING_OPERATOR_ACCOUNT_NOT_FOUND`, `BILLING_OPERATOR_ACCOUNT_MISMATCH`, `BILLING_OPERATOR_PAYMENT_MISMATCH` and `BILLING_OPERATOR_RESERVATION_NOT_FOUND` require the exact billing account and original target. `BILLING_OPERATOR_WORK_ACTIVE` preserves the active worker claim. `BILLING_OPERATOR_RESERVATION_NOT_UNKNOWN` refuses another settlement. `BILLING_OPERATOR_COMMIT_UNKNOWN` requires status readback and the same saved operation file; do not replace its UUID. `BILLING_OPERATOR_CLEANUP_FAILED` means COMMIT was acknowledged before cleanup failed. Read status to check the saved result separately from provider completion. These commands require an operator role and are unavailable to app and agent credentials.

Updated 2026-10-17: operator incident delivery stops on `INCIDENT_LEASE_LOST`, `INCIDENT_PAYLOAD_CONFLICT` or `INCIDENT_RECOVERY_REQUIRED`. Preserve the original event, attempt and delivery key. `INCIDENT_RECEIPT_UNKNOWN`, `INCIDENT_TRANSPORT_UNKNOWN` and `INCIDENT_SENDER_UNKNOWN` do not prove non-delivery and cannot justify a replacement send. `INCIDENT_DESTINATION_UNAVAILABLE` leaves configuration to an operator. These internal delivery states do not change account money or resolve incidents.

Updated 2026-10-17: `DATABASE_UNAVAILABLE` can follow a connection loss after COMMIT was sent. It does not prove rollback. Keep the same request or operation identity and read its saved status before retrying. A native connection error blocks further work on that transaction; it cannot turn a caught database failure into a successful response.

Updated 2026-10-17: `UPLOAD_RECOVERY_UNAVAILABLE` stops an owner upload before submission when the browser cannot preserve its pending request. Check Library and browser storage before another attempt. An uncertain upload keeps its original request ID when the same owner reselects the same file in the same workspace after reload. Do not clear recovery data to retry an unknown result.

Updated 2026-10-17: `UPLOAD_UNCONFIRMED` keeps the original owner upload request after a lost or unreadable response. Check Library, then reselect the same file to recover it. `UPLOAD_CANCELLED` confirms that the old upload ended; a later explicit file selection starts a new request. Neither response automatically sends another file.

Updated 2026-10-17: internal retention completion reports `RETENTION_CONTENT_SCOPE_CHANGED` when later post bindings fall outside the reviewed set, and `RETENTION_COMPLETION_RECEIPT_REQUIRED` when the final file/content receipt is missing or does not match. Keep both fences and review the original generation. `STORAGE_RUNTIME_PROOF_REQUIRED` still blocks automatic completion; a test receipt or operator flag cannot replace runtime proof.

Updated 2026-10-17: an expired owner upload is cancelled before its saved browser request is cleared. After confirmed cancellation, select the file again to start a new request. If cancellation is uncertain or the upload closed concurrently, the original request stays available for recovery.

Updated 2026-10-18: `CAPTION_POST_BINDING_REQUIRED` blocks retention when an old caption has no immutable database link to its post. Preserve the row for operator review; do not infer a deletion target from its JSON. `CAPTION_CONTENT_REMAINS` blocks completion if caption text remains for a post already marked removed. Neither result permits a replacement DELETE or a quota adjustment.

Updated 2026-10-18: `retention-storage-cancel-pending` keeps a canceled storage fence visible in operator findings after payment access is restored. It remains visible after sender drain until the original cancellation is repeated and the fence is released. Upload and website senders record `not_sent` only when the original invocation proves that the SDK call never began. An abort, timeout or rejected response after dispatch remains unknown; it does not release byte reservations or permit deletion.

Updated 2026-10-18: `SCHEDULE_SETTINGS_UNSUPPORTED` also stops a period-end plan change when an applied coupon is no longer redeemable. Review that discount before changing the plan. This refusal creates no Portal session or schedule. An existing native schedule can still be removed by its exact displayed selection; removal does not reapply a lost discount.

Caption requests keep their original paid operation when the post is later edited or approved. Replay the same request ID and input to read the saved outcome. A changed input returns `IDEMPOTENCY_CONFLICT`; an unknown outcome must not start another paid request automatically. The retired post planner cannot start a new operation. Original paid history and reconciliation remain available.
