{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Shuffll Engage jobs, retries, and errors","projectTitle":"Shuffll Developers","lang":"en","image":"/assets/icon-light.cf77c9f50f367b5652a57cbdbd6d9a5881b87349c1b0643a9f667e0d2e220f90.42541b0d.png","description":"Handle Shuffll Engage asynchronous jobs, revisions, retries, rate limits, and errors without duplicating campaign actions.","siteUrl":"https://api-docs.shuffll.com","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://shuffll.com/#organization","name":"Shuffll","url":"https://shuffll.com"},{"@type":"WebSite","@id":"https://api-docs.shuffll.com/#website","name":"Shuffll Developers","url":"https://api-docs.shuffll.com","inLanguage":"en","publisher":{"@id":"https://shuffll.com/#organization"}},{"@type":"WebAPI","@id":"https://api-docs.shuffll.com/engage#api","name":"Shuffll Engage API and MCP","url":"https://engage.shuffll.com","documentation":["https://api-docs.shuffll.com/engage","https://api-docs.shuffll.com/openapi/engage.json"],"serviceType":"Video campaign API and MCP","provider":{"@id":"https://shuffll.com/#organization"}},{"@type":"WebAPI","@id":"https://api-docs.shuffll.com/guides#api","name":"Shuffll Video Production API","url":"https://api.shuffll.com/api/v1","documentation":["https://api-docs.shuffll.com/apis","https://api-docs.shuffll.com/openapi/video-production.yaml"],"serviceType":"Video production REST API","provider":{"@id":"https://shuffll.com/#organization"}}]},"llmstxt":{"hide":false,"title":"Shuffll Engage API and MCP — Shuffll Developers","description":"Shuffll Engage connects agentic creation, catalog-driven campaigns, overlays and multilingual video through API and MCP. Video Production covers individual video projects.","details":{"content":"Start with [Shuffll Engage](https://api-docs.shuffll.com/engage). Read [which API to use](https://api-docs.shuffll.com/choose-api) and the [FAQ](https://api-docs.shuffll.com/faq) for scope, endpoints, and authentication. REST references are separate: [Engage](https://api-docs.shuffll.com/engage/openapi) and [Video Production](https://api-docs.shuffll.com/apis). Machine-readable OpenAPI downloads: [Engage JSON](https://api-docs.shuffll.com/openapi/engage.json) and [Video Production YAML](https://api-docs.shuffll.com/openapi/video-production.yaml). Legacy flat-video-v1 restrictions apply to that rendering workflow. Check live workspace access and operation-specific environment requirements.\n"},"sections":[{"title":"Shuffll Engage API and MCP","includeFiles":["engage/**/*.md"]},{"title":"Choose an API and get answers","includeFiles":["choose-api.md","faq.md"]},{"title":"Shuffll Video Production API","includeFiles":["guides/*.md","integrations/*.md"]},{"title":"Support","includeFiles":["contact.md"]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"shuffll-engage-jobs-retries-and-errors","__idx":0},"children":["Shuffll Engage jobs, retries, and errors"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mutations-and-revisions","__idx":1},"children":["Mutations and revisions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["REST mutations that require idempotency accept ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]},": 1–200 printable ASCII characters. Retain the same key for retries of the same uncertain request with identical input. Use a new value for a genuinely new action."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Revision-guarded mutations also require ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["If-Match"]}," with the opaque revision from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ETag"]}," or a job result. If a revision is missing or stale, read the current resource and review the change before retrying. MCP expresses these values as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operation_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expected_revision"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"asynchronous-work","__idx":2},"children":["Asynchronous work"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A mutation may return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," for a terminal job or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," while work remains. For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]},", use the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Location"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]},". Do not construct a polling URL from an unrelated site address. Job responses can include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pollAfterSeconds"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Terminal states are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["succeeded"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partially_failed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]},". Report the actual state and inspect result metadata; receiving a job identifier is not evidence of success."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-failures","__idx":3},"children":["Handling failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["REST errors contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.requestId"]},". Rate-limited responses include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]},". Honor it and avoid immediate retry loops. Unknown fields, duplicate query keys and fields shadowing path variables are rejected."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When access fails, inspect the configured workspace, key status and permitted scopes. Do not silently switch to another user's credentials. A denied MCP tool may be absent from discovery because the catalog is filtered by current capabilities."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For support, retain the request ID and operation name. Exclude authorization headers, API keys, temporary upload capabilities and personal recipient data from logs or support messages."]}]},"headings":[{"value":"Shuffll Engage jobs, retries, and errors","id":"shuffll-engage-jobs-retries-and-errors","depth":1},{"value":"Mutations and revisions","id":"mutations-and-revisions","depth":2},{"value":"Asynchronous work","id":"asynchronous-work","depth":2},{"value":"Handling failures","id":"handling-failures","depth":2}],"frontmatter":{"seo":{"title":"Shuffll Engage jobs, retries, and errors","description":"Handle Shuffll Engage asynchronous jobs, revisions, retries, rate limits, and errors without duplicating campaign actions."}},"lastModified":"2026-10-25T17:27:35.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/engage/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}