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

# Error Handling Overview

> Common errors and how to handle them

## Common Error Responses

### Authentication Errors

```json theme={null}
{
  "detail": "Authentication required. Provide Authorization: Bearer <token> header (OAuth 2.1) or X-API-Key header."
}
```

**Solution**: Check your API key or token is correct and included in headers.

<Card title="Authentication Errors" icon="key" href="/errors/authentication">
  Learn more about authentication errors
</Card>

### Template Required

```json theme={null}
{
  "requires_template": true,
  "message": "Please select a template from the list below",
  "available_templates": [...],
  "default_template_id": null
}
```

**Solution**: Call `list_templates` first, then provide a `template_id` in your request.

<Card title="Template Required" icon="palette" href="/errors/template-required">
  Learn how to handle template requirements
</Card>

### Credit/Quota Exceeded

```json theme={null}
{
  "error": "Insufficient credits",
  "error_code": "CREDITS_EXHAUSTED"
}
```

**Solution**: Check your account credits/usage limits in the web app at `https://app.poesius.com`.

### Generation Failed

```json theme={null}
{
  "status": "failed",
  "error": "Content generation failed",
  "details": {...}
}
```

**Solution**:

* Check document format is supported (PDF, DOCX, TXT, MD)
* Verify document is not corrupted
* Try with simpler instructions
* Check document size (keep under 50MB)
* Contact support if issue persists

### Invalid File Type

```json theme={null}
{
  "detail": "Invalid file type. Only .pptx and .ppt files are allowed."
}
```

**Solution**:

* Ensure you're uploading a PowerPoint template file (.pptx or .ppt)
* Check file extension matches the actual file type
* Re-save the file in PowerPoint format if needed

### File Too Large

```json theme={null}
{
  "detail": "File size exceeds maximum allowed size of 50MB"
}
```

**Solution**:

* Reduce file size by compressing images
* Remove unnecessary content
* Split large documents into smaller files
* Use document optimization tools

### Template Not Found

```json theme={null}
{
  "detail": "Template not found"
}
```

**Solution**:

* Verify the template ID is correct
* Check that the template belongs to your account
* List templates to see available template IDs
* Ensure the template hasn't been deleted

### Rate Limit Exceeded

```json theme={null}
{
  "detail": "Rate limit exceeded",
  "retry_after": 60
}
```

**Solution**:

* Wait for the specified time before retrying
* Check your subscription tier limits
* Implement exponential backoff in your code
* Consider upgrading your plan for higher limits

## Status Polling

When using async endpoints, poll the status endpoint properly:

<Card title="Status Polling" icon="circle-check" href="/errors/status-polling">
  Learn about proper status polling
</Card>

## Best Practices

* **Always Check Status**: Don't assume generation succeeded
* **Handle Timeouts**: Set maximum wait times for async operations
* **Retry Logic**: Implement retry logic for transient errors
* **Error Logging**: Log errors for debugging
* **User Feedback**: Provide clear error messages to users

## Error Codes

| Code                  | Description                          | Solution                                   |
| --------------------- | ------------------------------------ | ------------------------------------------ |
| `AUTH_REQUIRED`       | Authentication missing or invalid    | Check API key/token                        |
| `TEMPLATE_REQUIRED`   | Template not provided and no default | Provide `template_id`                      |
| `CREDITS_EXHAUSTED`   | Account credits depleted             | Check account limits in web app            |
| `INVALID_DOCUMENT`    | Document format not supported        | Use supported formats (PDF, DOCX, TXT, MD) |
| `GENERATION_FAILED`   | Content generation error             | Check document and retry                   |
| `RATE_LIMIT_EXCEEDED` | Too many requests                    | Wait and retry after `retry_after` seconds |
| `INVALID_FILE_TYPE`   | File type not allowed                | Use .pptx or .ppt for templates            |
| `FILE_TOO_LARGE`      | File exceeds size limit              | Reduce file size (max 50MB)                |
| `TEMPLATE_NOT_FOUND`  | Template ID doesn't exist            | Verify template ID                         |
| `UNAUTHORIZED_ACCESS` | Access denied to resource            | Check resource ownership                   |

<Card title="Authentication Errors" icon="key" href="/errors/authentication">
  Detailed authentication error handling
</Card>