Errors

The error envelope and what each code means.

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.