> ## Documentation Index
> Fetch the complete documentation index at: https://docs-slidekit.theduomi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP error shapes, async job failures, and practical remediation guidance.

# 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:

```json theme={"dark"}
{
  "detail": "Template with ID 'tmpl_123' not found"
}
```

Pydantic validation errors use `detail` as an array:

```json theme={"dark"}
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "template_slide_id"],
      "msg": "Field required"
    }
  ]
}
```

Unhandled server errors use the API's fallback shape:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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.