Errors

The API has two error surfaces:

Request errors returned immediately by an endpoint.
Async job failures returned inside generation or analysis status responses.

Request Error Shape

Most route, auth, and validation errors use FastAPI’s standard shape:

{
  "detail": "Template with ID 'tmpl_123' not found"
}

Pydantic validation errors use detail as an array:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "template_slide_id"],
      "msg": "Field required"
    }
  ]
}

Unhandled server errors use the API’s fallback shape:

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error occurred",
    "details": {}
  }
}

Common HTTP Errors

Status	Common cause	What to do
`400`	Invalid request body, malformed multipart form, invalid chart update data, invalid slide number	Check the request body against the endpoint schema and block-specific guide
`401`	Missing `X-API-Key`, or missing `X-Org-Name` in development/test mode	Send the correct auth header
`403`	Invalid/disabled API key, or `org_name` does not match the API key’s organization	Use a valid key for the target organization
`404`	Template, analysis, slide, generation, or generated file was not found	Verify the ID, organization, and whether the template/generation still exists
`422`	Schema validation failed before route logic ran	Inspect the `detail[]` array for the exact field path
`429`	Too many pending or processing generation requests	Retry later or increase the configured generation concurrency
`500`	Unexpected server error	Check server logs; in production, details are intentionally hidden
`503`	Readiness check failed	Check database connectivity and deployment health

Async Job Failures

Generation, deck generation, chart updates, and template analysis run asynchronously. A request can return 202 and still fail later. Poll the status endpoint and inspect:

top-level status
top-level error
slide_results[].error for deck generation

Example failed generation status:

{
  "generation_id": "gen_abc123",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Template file not found in storage",
    "details": null
  }
}

Common async error codes include:

Code	Meaning
`NO_VALID_SLIDES`	No slide in the deck request could be validated
`GENERATION_FAILED`	Slide or deck generation failed while processing
`GENERATION_TIMEOUT`	The generation worker exceeded the configured timeout
`CHART_UPDATE_FAILED`	Chart update processing failed
`SERVER_RESTART`	Startup recovery marked an interrupted job as failed after a restart

Practical Debugging

For 404, confirm you are using a slideId from the latest template analysis and the API key belongs to the same organization.
For 422, use the field path in detail[].loc to find the invalid payload field.
For partial deck results, download may still be available; inspect slide_results to decide whether to use or regenerate the deck.
For storage-related failures, verify the template/generated storage backend and bucket or path permissions.
For repeated 429, tune generation worker settings or reduce concurrent requests.

Endpoints

Supporting Reference

Errors

Errors

Request Error Shape

Common HTTP Errors

Async Job Failures

Practical Debugging

​Errors

​Request Error Shape

​Common HTTP Errors

​Async Job Failures

​Practical Debugging

Errors

Request Error Shape

Common HTTP Errors

Async Job Failures

Practical Debugging