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
{
"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
| Code | HTTP | What it means |
|---|---|---|
unauthenticated | 401 | No API key was sent. |
invalid_api_key | 401 | The key is not valid or was revoked. |
insufficient_scope | 403 | The key lacks the scope the call needs (scope says which). |
rate_limited | 429 | Too many requests. Wait for Retry-After seconds. |
bad_request | 400 | A field is missing or wrong (field says which). |
max_credits_required | 400 | A paid call came without max_credits. The error carries the quote and says what to send. |
over_max_credits | 402 | The call would cost more than max_credits (needed is the price). Nothing was started. |
confirm_required | 409 | The call is above 5,000 credits or needs a review. Send confirm: true. |
blocked | 422 | One or more shots cannot run yet. Fix them, or send skip_blocked: true to run the rest. |
nothing_to_do | 422 | There is nothing to make: every shot already has one, or none was named. |
not_found | 404 | The project, shot, job or run does not exist for this account. |
idempotency_key_reused | 422 | The Idempotency-Key was used with a different request. |
idempotency_in_progress | 409 | A request with this Idempotency-Key is still running. |
tool_unavailable | 503 | The 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
| Code | What to do |
|---|---|
max_credits_required | Read the quote in the error and send a max_credits at or above it. |
over_max_credits | Nothing was started. Raise the cap, or change what you make (a shorter clip, a cheaper model), then ask again with dry_run. |
confirm_required | The spend is above 5,000 credits. Check the quote, then send confirm: true if you mean it. |
blocked | A 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_key | The key is wrong or was revoked. Make a new one under Settings, API keys. |
insufficient_scope | Make a key with the scope in the error: generate to plan and make things, export to export. |
idempotency_in_progress | The 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 see | What to do |
|---|---|
invalid_token | The 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 plan | Add 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.
More docs
- 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
- Chrome extension privacy policyWhat the Ziztu Chrome extension collects (nothing) and the one permission it asks for.
- Ziztu changelogWhat changed in Ziztu, newest first, in plain words.
Make a key and try a call.
Start for $10 a month. Ziztu starts at $10 a month for 7,000 credits.