Skip to main content

​
Common Error Responses

​
Authentication Errors

{
  "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.

Authentication Errors

Learn more about authentication errors

​
Template Required

{
  "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.

Template Required

Learn how to handle template requirements

​
Credit/Quota Exceeded

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

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

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

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

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

{
  "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:

Status Polling

Learn about proper status polling

​
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

CodeDescriptionSolution
AUTH_REQUIREDAuthentication missing or invalidCheck API key/token
TEMPLATE_REQUIREDTemplate not provided and no defaultProvide template_id
CREDITS_EXHAUSTEDAccount credits depletedCheck account limits in web app
INVALID_DOCUMENTDocument format not supportedUse supported formats (PDF, DOCX, TXT, MD)
GENERATION_FAILEDContent generation errorCheck document and retry
RATE_LIMIT_EXCEEDEDToo many requestsWait and retry after retry_after seconds
INVALID_FILE_TYPEFile type not allowedUse .pptx or .ppt for templates
FILE_TOO_LARGEFile exceeds size limitReduce file size (max 50MB)
TEMPLATE_NOT_FOUNDTemplate ID doesn’t existVerify template ID
UNAUTHORIZED_ACCESSAccess denied to resourceCheck resource ownership

Authentication Errors

Detailed authentication error handling