Errors

Use the error object on non-2xx responses for programmatic error handling. It includes a stable error code, retry guidance, a human-readable message, optional structured details, and a request id for support.

HTTP Error Response

{
  "detail": "Invalid API key",
  "error": {
    "code": "INVALID_API_KEY",
    "status_code": 401,
    "retryable": false,
    "message": "Invalid API key",
    "details": {},
    "request_id": null
  }
}

Error Fields

Field	Type	Description
`error.code`	string	Stable machine-readable error code.
`error.status_code`	number	HTTP status code returned by the request.
`error.retryable`	boolean	Whether retrying the same request may succeed.
`error.message`	string	Human-readable error message.
`error.details`	object	Additional structured details when available.
`error.request_id`	string or null	Request id for support. This is `null` when the request failed before a request record was created.

Async Task Failures

For failed async tasks, poll /task_status/{task_id} and read task_error.

{
  "task_id": "9649d202-03ac-437a-80e8-ff91ff4ace67",
  "task_status": "FAILURE",
  "task_result": null,
  "task_info": null,
  "task_error": {
    "code": "EXPORT_FAILED",
    "status_code": 500,
    "retryable": true,
    "message": "The presentation export failed.",
    "details": {},
    "request_id": "cmqf2lohi00017wlp3du979zt"
  }
}

Error Codes

Authentication and billing

Code	Status	Retryable	Meaning
`MISSING_API_KEY`	401	No	The `X-API-Key` header was not provided.
`INVALID_API_KEY`	401	No	The API key is invalid or inactive.
`NO_API_SUBSCRIPTION`	402	No	No active API subscription was found.
`INSUFFICIENT_API_CREDITS`	403	No	The API key does not have enough credits for the request. `details` carries `required_credits` and `available_credits`.
`USER_NOT_FOUND`	400	No	The user behind the API key could not be resolved.

Invalid requests

Code	Status	Retryable	Meaning
`VALIDATION_FAILED`	422	No	The request body, query, or path parameters failed validation. `details.errors` lists the failures.
`INVALID_LENGTH`	422	No	The requested presentation length is not valid for this request.
`INVALID_LAYOUT`	400	No	A layout name was given for a template that does not support it.
`INVALID_SLIDE_POSITION`	422	No	The slide position is outside the presentation.
`UNSUPPORTED_SLIDE_EDIT`	422	No	Cover and table-of-contents slides cannot be edited.
`UNSUPPORTED_FILE_TYPE`	400	No	The uploaded file type is not supported.
`FILENAME_REQUIRED`	400	No	The uploaded file is missing a filename.
`FILE_TOO_LARGE`	413	No	The uploaded file exceeds the allowed size.

Missing or inaccessible resources

Code	Status	Retryable	Meaning
`DOCUMENT_NOT_FOUND`	404	No	One or more referenced documents were not found or are unavailable.
`VERSION_NOT_FOUND`	404	No	The `version_id` does not exist, is older than the 90-day retention window, or belongs to another API key.
`TASK_ID_NOT_FOUND`	404	No	The task id does not exist or is not visible to this API key.
`REQUEST_NOT_FOUND`	404	No	The presentation request id was not found.
`REUSABLE_SECTION_NOT_ACCESSIBLE`	403	No	The reusable section is not available to this user.
`DESIGN_KIT_NOT_ACCESSIBLE`	403	No	The design kit is not available to this user.

Transient failures

These are the only codes worth retrying. Retry with exponential backoff.

Code	Status	Retryable	Meaning
`REQUEST_NOT_READY`	404	Yes	The request exists but does not have a result yet. Keep polling.
`DOWNLOAD_NOT_AVAILABLE`	404	Yes	A download URL is not available yet. Keep polling.
`RATE_LIMITED`	429	Yes	Too many requests. Back off and retry.
`GENERATION_FAILED`	500	Yes	Presentation generation failed after the task started.
`EXPORT_FAILED`	500	Yes	The presentation export failed after the task started.
`TASK_FAILED`	500	Yes	The async task failed and no more specific error was stored.
`INTERNAL_ERROR`	500	Yes	An unexpected server error occurred.