# Troubleshooting

Common problems and how to fix them. Each entry follows the same shape: **symptom -> cause -> fix.**

Errors from ZenCreator tools come back as tool results, not crashes — your client sees a short, actionable message telling it what to try next. The notes below explain what each one means and how to recover.

---

## "Out of credits" (HTTP 402)

**Symptom.** A generation tool fails and the result says you're out of ZenCreator credits, or a tool returns a `structuredContent` payload like:

```json
{
  "error_code": "insufficient_credits",
  "out_of_credits": true,
  "purchase_url": "https://app.zencreator.pro/billing",
  "message": "You're out of ZenCreator credits. Top up at https://app.zencreator.pro/billing to keep generating."
}
```

**Cause.** Generation spends credits, and your balance reached zero. The backend returns HTTP 402 with the structured signal above.

**Fix.** Top up at [https://app.zencreator.pro/billing](https://app.zencreator.pro/billing), then retry the generation.

**Avoid it next time.** The same `out_of_credits` flag and `purchase_url` also appear in `zencreator_get_me`, so you can check your balance proactively before submitting work. And always price a job before you commit to it: call `zencreator_estimate_price` for one candidate, or `zencreator_compare_prices` to shop across a generation tool's models (cheapest first). See [./tools/account.md](./tools/account.md).

---

## "Adult content is disabled" / NSFW request refused

**Symptom.** An NSFW generation is rejected, or a model you asked for isn't allowed on your account.

**Cause.** Two account gates control uncensored generation:

- `nsfw_allowed` — adult content must be enabled on the account.
- `is_trusted` — required for models marked **(trusted)**.

Both are reported by `zencreator_get_me`. If `nsfw_allowed` is `false`, the request is refused before any credits are spent.

**Fix.**

- If `nsfw_allowed` is `false`: enable adult content in your ZenCreator account settings at [https://app.zencreator.pro](https://app.zencreator.pro), then retry.
- If the tool or model is **(trusted)** / 🔒 and you aren't trusted yet: Trusted Status is granted **automatically after your first successful payment** (buy any credit pack in Billing) and is permanent — make that first payment, or pick a non-trusted model for the same generation tool. Use `zencreator_get_tool_schema` to see which models a generation tool offers.

If your orchestrating client refuses to author explicit prompts, the optional `zencreator_craft_prompt` helper (present only on deployments with the prompt-agent sidecar) can write model-specific NSFW prompts for you — it spends no ZenCreator credits. See [./tools/generation.md](./tools/generation.md).

---

## Connector shows "disconnected" or returns 401

**Symptom.** The ZenCreator connector reads as disconnected, tools stop appearing, or a call comes back with an authentication failure ("re-authorize with the ZenCreator MCP server").

**Cause.** Your access token expired and couldn't be refreshed, or the authorization was revoked. The MCP server is OAuth-only — every request needs a valid, audience-bound token.

**Fix.** Re-run the OAuth login. Tokens normally refresh automatically; you only need to do this when the grant was revoked or refresh failed.

- **Claude Code:** start `claude`, run `/mcp`, pick `zencreator`, choose **Authenticate**, approve in the browser. Check state with `claude mcp list` (shows "Needs authentication" until you log in). See [./connect/claude-code.md](./connect/claude-code.md).
- **Claude Desktop / Claude.ai (web):** reconnect the custom connector in **Settings -> Connectors** and complete the browser login again. See [./connect/claude-ai.md](./connect/claude-ai.md).
- **Cursor:** trigger the server again so it re-runs the browser OAuth login. See [./connect/cursor.md](./connect/cursor.md).
- **ChatGPT:** reconnect the connector under **Settings -> Connectors** and complete the OAuth login. See [./connect/chatgpt.md](./connect/chatgpt.md).

There are no API keys to rotate — the whole flow happens in your browser.

---

## Video generation times out

**Symptom.** A video job (e.g. `videogen`, `text_to_video`, `video2video`, `lipsync`, `video_upscaler`) hangs or the request aborts before finishing.

**Cause.** Video takes far longer than images (typically ~60-180s). `zencreator_run_and_wait` blocks until the job reaches a terminal status — fine for images this turn, but too slow for video, so the call can time out.

**Fix.** Don't wait synchronously for video. Instead:

1. Submit with `zencreator_create_task` — it returns a task id immediately.
2. Poll `zencreator_get_task` until the call reaches a terminal status (space your polls — see the rate-limit note below).
3. Fetch the result with `zencreator_get_call_result` to get the full output and the generated `asset_id`s (per-call output is lazy and is `null` while polling).

Reserve `zencreator_run_and_wait` for images. See [./tools/generation.md](./tools/generation.md).

---

## Rate limited (HTTP 429)

**Symptom.** A tool result says the rate limit was exceeded and to back off.

**Cause.** Too many requests in a short window — most often tight polling loops on `zencreator_get_task` or `zencreator_get_processing_tasks`.

**Fix.** Back off and retry after a few seconds. Space out polling — wait at least **2 seconds** between polls — and prefer `zencreator_get_processing_tasks` as a cheap "is anything still running?" check instead of hammering `zencreator_get_task`.

---

## Images don't show up in the chat

**Symptom.** A generation succeeds but no image appears in the conversation.

**Cause.** Some clients only render MCP images inside the tool-result panel, which can be collapsed by default — the image is there, just hidden.

**Fix.**

- Expand the tool-result panel to view the inline image.
- Or call `zencreator_get_asset_preview_url` with the inline option, which attaches the preview image as an image content block so it renders directly in chat. Inline previews are capped at **2 MB per image** and **8 MB total per call**; above that the tool falls back to returning a URL with a note.
- Or open the original via `zencreator_get_asset_download_url` (presigned). For many assets at once, use the batch variants (`zencreator_get_asset_preview_urls` / `zencreator_get_asset_download_urls`).

See [./tools/assets.md](./tools/assets.md).

---

## Response got truncated

**Symptom.** A long tool response ends with a truncation note saying to paginate or switch format.

**Cause.** Text responses larger than ~25,000 characters are trimmed to keep the payload manageable.

**Fix.**

- For list tools, paginate: pass `limit` (1-100, default 20) and `offset` (default 0), then feed the returned `next_offset` back as `offset` for the next page.
- Or set `response_format: "json"` for a more compact raw payload.
- Either way, the full data is always in the `structuredContent` object, so clients with output-schema support already have everything regardless of the text format.

---

## Validation error (HTTP 422)

**Symptom.** A tool result says validation failed — commonly on `zencreator_create_task` or `zencreator_run_and_wait`.

**Cause.** Your input didn't match the generation tool's schema (wrong field name, missing required field, an out-of-range value, or an invalid model/enum).

**Fix.** Re-check your input against the schema. Call `zencreator_get_tool_schema` for the generation tool you're submitting (e.g. `by_prompt`, `image_editor`, `faceswap`) — it returns the full input/output JSON Schema plus prompt and model guidance. Fix the offending fields and resubmit. See [./tools/generation.md](./tools/generation.md).

A related **HTTP 400 (Bad request)** has the same remedy: check the input fields against the tool's input schema.

---

## See also

- [./tools/account.md](./tools/account.md) — credits, balance, `zencreator_get_me`, transaction history.
- [./tools/generation.md](./tools/generation.md) — submitting jobs, polling, schemas, models.
- [./tools/assets.md](./tools/assets.md) — previews, downloads, inline images.
- Connect guides: [Claude Code](./connect/claude-code.md) · [Claude.ai / Desktop](./connect/claude-ai.md) · [Cursor](./connect/cursor.md) · [ChatGPT](./connect/chatgpt.md).