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": "Design kit is not available to this user",
  "error": {
    "code": "DESIGN_KIT_NOT_ACCESSIBLE",
    "status_code": 403,
    "retryable": false,
    "message": "Design kit is not available to this user",
    "details": {},
    "request_id": "cmqf2lohi00017wlp3du979zt"
  }
}

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"
  }
}

Common Error Codes

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.
`VALIDATION_FAILED`	422	No	The request body, query, or path parameters failed validation.
`DESIGN_KIT_NOT_ACCESSIBLE`	403	No	The design kit is not available to this API key.
`REUSABLE_SECTION_NOT_ACCESSIBLE`	403	No	The reusable section is not available to this API key.
`INVALID_LENGTH`	400	No	The requested length is invalid for the generation settings.
`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.
`DOCUMENT_NOT_FOUND`	404	No	One or more referenced documents were not found or are unavailable.
`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.
`REQUEST_NOT_READY`	404	Yes	The request exists but does not have a result yet.
`DOWNLOAD_NOT_AVAILABLE`	404	Yes	A download URL is not available yet.
`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.

Retryable errors should be retried with backoff. Non-retryable errors require changing the request, API key, subscription, credits, or referenced resources before retrying.