marketing.generations.cancel
Stop a generation
POST/marketing/generations/{id}/cancel
Stop a generation that has not started being worked. One already in progress finishes its current step, so a cancel that arrives late is 200 with the generation unchanged. Read state to see which happened.
curl -X POST "https://api.gogoscreen.com/api/v1/marketing/generations/<id>/cancel" \
-H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"At a glance
| Fact | Detail |
|---|---|
| Scopes | marketing:write |
| Credentials | a signed in dashboard session or an API key. |
| Rate limit | 120 requests a minute per credential, in the write class. |
| Idempotency | Required. Send an Idempotency-Key header; a retry with the same key and the same body returns the stored answer with Idempotent-Replayed: true. How idempotency works. |
| MCP tool | marketing_generations_cancel |
| Always sets | Cache-Control: private, no-store |
| Verified email | Required. An account whose email address is not verified meets 403 email_unverified before the operation runs. |
| Marketing videos | Required. An account without marketing videos enabled meets 403 feature_disabled before the operation runs. |
200 OK
Stop a generation
| Name | Type | Description | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| generation | object | ||||||||||||||||||||||||||||||||||
10 fields inside generation
| |||||||||||||||||||||||||||||||||||
| resource | object | any keys | |||||||||||||||||||||||||||||||||
| Header | Meaning |
|---|---|
Cache-Control | Always private, no-store. |
Idempotent-Replayed | Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done. |
Errors
Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.
| Code | Status | When it happens | What to do |
|---|---|---|---|
| brand_logo_source_mismatch | 400 | The logo choice names a source other than the one the generation is being built from. | Choose a logo from the source this generation reads, or use the brand kit's own. |
| idempotency_key_required | 400 | A mutating operation arrived over HTTP with no Idempotency-Key header. It is refused before the body is parsed, so a caller missing both learns about both at once. | Add an Idempotency-Key header of up to 128 characters, unique to this request. Over MCP the same value goes in the idempotencyKey tool argument. |
| unsupported_duration | 400 | The design does not offer that length. | details.durations lists what it does offer. Pick one of those. |
| validation_failed | 400 | The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored. | Read details.issues. Each entry carries a path, a message and a machine readable code. Fix every named field and send the request again; the same body always fails the same way. |
| unauthorized | 401 | No credential was presented, or the key is unknown, revoked or expired, or an X-API-Key header carried something that is not an API key. details.reason says which. | Send Authorization: Bearer gsk_live_…. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in Authorization, never in X-API-Key. |
| insufficient_seconds | 402 | The account's seconds wallet does not hold enough time for the video that was asked for. It is the only refusal on this surface that is a 402. | details.needed and details.available are the two numbers. Buy more time, or ask for a shorter video. Retrying without changing either fails the same way. |
| forbidden_scope | 403 | The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. keys.* and assistant.* are user only and can never be called by a key. | details.requiredScopes and details.missingScopes name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When details.allowedActors is present, no key can call this operation at all. |
| generation_not_found | 404 | No generation of that id belongs to this account. | Check the id. A generation belonging to another account answers the same way. |
| not_found | 404 | No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403. | Check the id. Do not treat this as a permissions problem. |
| project_not_found | 404 | No marketing project of that id belongs to this account. | Check the id. A project belonging to another account answers the same way. |
| source_not_found | 404 | No website source of that id belongs to this account. | Check the id. A source belonging to another account answers the same way. |
| source_version_not_found | 404 | No such version of that website source. | Read the source to see which versions exist, then name one of those. |
| brand_kit_required | 409 | The generation needs a brand kit and the account has never saved one. | Save one with PUT /marketing/brand-kit first. name and accent are the two required fields. |
| brand_logo_not_retained | 409 | The generation asked for a logo the account no longer holds, because retention took it. | Pick a different logo choice, or scan the source again so a logo is held. |
| conflict | 409 | The request conflicts with the state the resource is in, and no more specific code applies. | Re-read the resource and decide from its current state. Retrying the same request unchanged will not help. |
| generation_busy | 409 | Another generation is already running for this source. One at a time per account. | Poll the running one until its state is terminal, or cancel it, then start the new one. |
| generation_idempotency_conflict | 409 | That idempotency key was already used on this account with a different generation request. | Use a fresh key for a different request. One key stands for one intent. |
| generation_not_retryable | 409 | A retry was asked for on a failure that a retry cannot change, for example a design that cannot fit the words. | Read retryable on the generation before asking. When it is false, fix the request and start a new generation. |
| idempotency_conflict | 409 | That idempotency key has already been used on this operation with a different request body. | Use a fresh key for a different request. A key stands for one intent, not for one attempt. |
| idempotency_in_progress | 409 | The first request under that key is still being worked. Two concurrent identical requests both reach the store and one of them is told this. | Wait the Retry-After seconds, which is 2, and send exactly the same request again with the same key. Do not change the body and do not mint a new key. |
| source_kind_mismatch | 409 | The project was made from a different kind of source than the one being used, for example a walkthrough render where a scanned website is expected. | Use the source the project was built from, or start a new project of the right kind. |
| source_owner_unavailable | 409 | The account cannot start new work, because it is blocked or scheduled for deletion. | Resolve the account's state, then retry. |
| source_version_mismatch | 409 | The version named belongs to a different website source. | Send a version number from the source you are naming. |
| source_deleted | 410 | The website source has been deleted. It still reads state: "cancelled". | Scan the site again with marketing.sources.create. |
| source_expired | 410 | The website source is past its retention window. | Scan the site again. Projects already built from it keep the version they were built from. |
| source_version_expired | 410 | That manifest version has been cleaned up. | Scan the site again and build from the new version. |
| campaign_copy_overflow | 422 | Words sent for a marketing scene do not fit the frame the design draws them in. The fit is measured, not guessed. | Shorten the fields details.fields names, then send the revision again. marketing.generations.preflight answers the same refusal before anything is created. |
| campaign_logo_aspect_unsupported | 422 | The logo's aspect ratio is not one any design can place. | Supply a logo closer to square or to a standard wordmark shape. |
| campaign_unsupported_claim | 422 | A statement sent for the film is not supported by anything the scanned website says. | Reword the claim so it repeats something the source actually says, or drop it. |
| campaign_visuals_insufficient | 422 | The design needs more pictures than the scanned source has. | details says how many are needed and which scenes are short. Scan a richer page, refresh the source, or choose a design with fewer picture slots. |
| invalid_campaign_narration | 422 | The narration request for a marketing film is not a valid shape. | Send narration as the operation's schema declares it, or omit it and let the design's default stand. |
| rate_limited | 429 | The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. details.scope is minute, day or account, or global when the product's own daily cap on voice previews is spent. | Wait the Retry-After seconds and retry. details.limit and details.resetAt say what was hit and when it reopens. The RateLimit-* headers on every answer let a client pace itself before it gets here. |
| internal_error | 500 | An unhandled failure inside this API. The original message is logged and never answered. | Retry once, then quote requestId to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe. |