ziztu
Make a video

Ziztu API errors and rate limits

The Ziztu API answers every failure with a JSON error that has a code you can switch on and a message you can show. This page lists each code, the HTTP status and the fix.

For AI agents: the documentation index is at /llms.txt, and every page here has a markdown version at the same address with .md added.

Updated

The shape of an error

An error
{
  "error": {
    "code": "over_max_credits",
    "message": "This would spend 1500 credits, more than max_credits (1000). Nothing more was started.",
    "max_credits": 1000,
    "needed": 1500
  }
}

Every error has a code you can switch on and a message you can show. Spend errors also carry the quote.

Switch on error.code, not on the message. Some errors add fields: scope on insufficient_scope, field on bad_request, and the quote or needed on spend errors.

Error codes

CodeHTTPWhat it means
unauthenticated401No API key was sent.
invalid_api_key401The key is not valid or was revoked.
insufficient_scope403The key lacks the scope the call needs (scope says which).
rate_limited429Too many requests. Wait for Retry-After seconds.
bad_request400A field is missing or wrong (field says which).
max_credits_required400A paid call came without max_credits. The error carries the quote and says what to send.
over_max_credits402The call would cost more than max_credits (needed is the price). Nothing was started.
confirm_required409The call is above 5,000 credits or needs a review. Send confirm: true.
blocked422One or more shots cannot run yet. Fix them, or send skip_blocked: true to run the rest.
nothing_to_do422There is nothing to make: every shot already has one, or none was named.
not_found404The project, shot, job or run does not exist for this account.
idempotency_key_reused422The Idempotency-Key was used with a different request.
idempotency_in_progress409A request with this Idempotency-Key is still running.
tool_unavailable503The Studio app is not available right now.

A paid call from an account with too few credits is refused with HTTP 402 before anything starts.

What to do about the common ones

CodeWhat to do
max_credits_requiredRead the quote in the error and send a max_credits at or above it.
over_max_creditsNothing was started. Raise the cap, or change what you make (a shorter clip, a cheaper model), then ask again with dry_run.
confirm_requiredThe spend is above 5,000 credits. Check the quote, then send confirm: true if you mean it.
blockedA shot cannot run yet. The quote says why. Fix it with the Director or in the Studio, or send skip_blocked: true to run the rest.
invalid_api_keyThe key is wrong or was revoked. Make a new one under Settings, API keys.
insufficient_scopeMake a key with the scope in the error: generate to plan and make things, export to export.
idempotency_in_progressThe first request with this Idempotency-Key is still running. Wait and ask again with the same key.

Rate limits

By default 120 requests a minute per key, and 30 paid POSTs a minute. A response carries X-RateLimit-Limit and X-RateLimit-Remaining. When you pass the limit you get HTTP 429 with the code rate_limited and a Retry-After header with the seconds to wait.

Wait for that time and retry. For a paid call, retry with the same Idempotency-Key so a call that did get through is not run twice.

Errors in an MCP client

What you seeWhat to do
invalid_tokenThe app's sign-in expired or was disconnected. Connect it again. A planner token on the full address (or the other way round) also gives this: connect again to the address you use.
Codex times out on a planAdd tool_timeout_sec = 180 to the ziztu entry in ~/.codex/config.toml. The default is 60 seconds.

The other codes above reach an MCP client as the same code in the tool result. The MCP server page has the full fix list.

Other ways to use Ziztu

  • The Ziztu Chrome extension turns any text you select on a web page into a micro drama or anime scene. Its privacy policy says what it collects: nothing.
  • Ziztu for Notion sends a Reel Factory plan to a Notion board and updates each row when the reel is made.
  • The connectors add Ziztu to Claude, ChatGPT, Codex, Cursor and Grok.

Frequently asked questions

What do Ziztu API errors look like?

Every failure is a JSON error with a code you can switch on, such as over_max_credits or insufficient_scope, and a message you can show. Spend errors carry the price. Past the rate limit you get HTTP 429 and a Retry-After header.

What does over_max_credits mean?

The call would cost more than the max_credits you sent. Nothing was started. The error carries the price as needed, so you can raise the cap or change what you make.

What are the Ziztu API rate limits?

By default 120 requests a minute per key and 30 paid requests a minute. Past the limit you get HTTP 429 and a Retry-After header with the seconds to wait.

Why do I get insufficient_scope?

The key lacks the scope the call needs. The error names it. Make a key with generate to plan and make things, or export to export.

What HTTP status does a paid call with too few credits return?

HTTP 402, before anything starts.

  • Use Ziztu from an AI agentTo make a micro drama from Claude Code, add the Ziztu MCP server with one command, ask the Director to plan your idea, then make…
  • Ziztu PlannerZiztu Planner brings the Script Writer and the Director into Claude and other MCP clients.
  • Ziztu Reel StudioZiztu Reel Studio is an MCP server at https://getziztu.com/mcp/reel.
  • Ziztu MCP toolsThe Ziztu MCP server has 30 tools. Here they are grouped by what they do, in the order an agent uses them, each with its…
  • Ziztu YouTube StudioZiztu YouTube Studio is an MCP server at https://getziztu.com/mcp/youtube.
  • Ziztu OpenAPI specThe Ziztu API is described as one OpenAPI 3.1 document at https://getziztu.com/openapi.json.
  • Ziztu API quickstartZiztu has a REST API.
  • Ziztu skills for agentsZiztu publishes two skills for AI agents under the MIT license: one writes micro drama series and episodes, the other writes…

Also on Ziztu

See all: Docs · Site map

Make a key and try a call.

Start for $10 a month. Ziztu starts at $10 a month for 7,000 credits.

Video
Image
Audio
Writing
Effects
Learn
PricingLog in
Theme