> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trypekto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope and what each code means.

Every error has the same shape:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "This operation requires presentations:create.",
    "request_id": "8d3c…",
    "details": { "required_scope": "presentations:create" }
  }
}
```

`code` is stable; `message` is for people and may change. `details` is present only when there's more to say.

## Codes

| Status | Code | Meaning |
| - | - | - |
| 400 | `missing_source` | Send at least one of `topic`, `content` or `instructions`. |
| 400 | `invalid_template_family` | Unknown carousel theme. `details.valid_template_families` lists the ids. |
| 400 | `unsafe_content` | The SVG or content contains scripts, event handlers or unsafe links. See [Rules for SVG](/guides/editing-projects#rules-for-svg). |
| 400 | `invalid_media` | `media_urls` must be files in your own Pekto media folder. |
| 400 | `missing_media` | Image and document posts need `media_urls`. |
| 400 | `invalid_schedule` | `scheduled_for` must be a future ISO 8601 time. |
| 400 | `invalid_post_type`, `missing_caption` | Check the post fields. |
| 400 | `invalid_logo_url` | `brand_logo_url` must be an https URL. |
| 400 | `invalid_title`, `invalid_status`, `empty_update` | Check the project fields. |
| 400 | `invalid_identifier`, `invalid_cursor` | An id isn't a UUID, or the cursor is stale. |
| 400 | `invalid_json`, `invalid_body` | The body must be a JSON object. |
| 401 | `unauthorized`, `invalid_token`, `invalid_api_key` | Missing, expired or revoked token. |
| 402 | `insufficient_credits` | Not enough credits; `details` has your balance and an upgrade link. |
| 403 | `insufficient_scope` | The key doesn't have the scope in `details.required_scope`. |
| 403 | `session_required` | API keys can only be managed from the Pekto app. |
| 404 | `project_not_found`, `job_not_found`, `scheduled_post_not_found`, `social_account_not_found` | It doesn't exist or isn't yours. |
| 404 | `route_not_found` | Check the method and path. |
| 409 | `api_key_limit_reached` | Revoke a key before creating another (20 max). |
| 409 | `generation_flow_required` | Create projects with `POST /presentations`. |
| 413 | `payload_too_large` | The body is over the size limit. |
| 429 | `rate_limit_exceeded` | Wait for `Retry-After` seconds. |
| 502 | `presentation_generation_failed` | Generation failed and your credits were refunded. Try again. |
| 500 | `internal_error` and other `*_failed` codes | Something went wrong on our side. Retry, then contact support with the `request_id`. |

## In MCP tools

MCP tools return the same `error` object as the tool result, marked as an error, so your AI tool can explain it or ask you what to do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.