Errors - Pekto

Every error has the same shape:

{
  "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.
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.