> For the complete documentation index, see [llms.txt](https://docs.perceptis.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perceptis.ai/perceptis-mcp-server/errors.md).

# Error codes

Tool calls that fail return an `{"error": "...", "code": "..."}` payload. The `code` is stable and safe to switch on.

## Auth and quota

| Code                   | Meaning                                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `insufficient_credits` | Organization credit balance is too low to start generation.                                                                                   |
| `rate_limited`         | Per-user rate limit exceeded — see [Credits and limits](/perceptis-mcp-server/credits-and-limits.md). Payload includes `retry_after_seconds`. |

HTTP `401` (no body) means the bearer API key is missing, invalid, or revoked, or the OAuth session has expired.

## Lookup failures

| Code                 | Meaning                                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `template_not_found` | The template id does not exist or is not accessible to your organization.                                        |
| `session_not_found`  | Session id does not exist or belongs to a different user.                                                        |
| `deck_not_found`     | Deck id does not exist or belongs to a different user.                                                           |
| `slide_not_found`    | Slide number is out of range for the deck.                                                                       |
| `org_not_found`      | The authenticated user has no active organization.                                                               |
| `missing_parameter`  | A required id (`session_id` or `deck_id`) was not supplied to `check_generation_status` or `show_slide_preview`. |

## Generation state

| Code                  | Meaning                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| `generation_failed`   | The underlying generation workflow failed. The session/deck cannot be recovered; start a new one.              |
| `session_empty`       | The session has no slides or successful versions yet.                                                          |
| `storyline_not_ready` | `render_deck` was called before the storyline phase finished. Poll `check_generation_status(deck_id=…)` first. |
| `render_not_complete` | `export_deck` was called before all slides finished rendering. Poll first.                                     |
| `deck_not_rendered`   | `edit_deck_slide` was called against a deck that has not been rendered yet.                                    |
| `artifacts_failed`    | `show_slide_preview` could not fetch the rendered PNG from storage. Retry; if persistent, regenerate.          |
| `export_timeout`      | The `.pptx` merge workflow did not finish within the polling window. Retry `export_deck`; it is idempotent.    |