File Size Limits
To ensure fair distribution of computing resources and back-end service stability, DeckFlow enforces specific limits on file processing, API request frequency, and quotas.
The maximum file size limit supported by each API and tool is listed below. Please ensure that your files do not exceed these thresholds before calling the task creation API:
| Feature / Tool Category | Max File Size | Supported Input Formats |
|---|---|---|
| Document Translation (Translate) | 500 MB | .pptx, .key, .pdf, .docx, .doc, .xlsx, .xls |
| HTML Packaging Tool (HTML Player Pack) | 50 MB | .html, .htm |
| HTML Converter (html2png / html2pptx) | 50 MB | .html, .htm (supports pasting HTML code) |
| Markdown Converter (markdown2png) | 10 MB | .md, .markdown (supports pasting Markdown text) |
| Image OCR (image.ocr) | 50 MB | image/* (e.g., JPG, PNG, etc.) |
| Image Resizing (image.resize) | 100 MB | image/* (e.g., JPG, PNG, etc.) |
| Image WebP Conversion (image.convertWebp) | 100 MB | image/* (e.g., JPG, PNG, etc.) |
| Video Compression (video.compress) | 300 MB | video/* (e.g., MP4, MOV, etc.) |
| Other Document & Presentation Tools | 300 MB | .pptx, .ppt, .key, .docx, .doc, .xlsx, .xls, .pdf, .zip |
API Error Status Codes
When an API request fails or task creation errors out, the API returns the corresponding HTTP status code and a JSON response with error details. The following table lists the system-wide status codes:
| Status Code | Error Code (code) |
Description / Scenario | Recommended Troubleshooting & Recovery Solution |
|---|---|---|---|
400 |
invalid_parameter |
Missing required parameters, invalid parameter format, or unsupported file formats. | Check and correct the type or params attributes in POST /tools/tasks. |
400 |
file_size_exceeded |
The uploaded file exceeds the maximum file size limit listed above. | Compress the file size or split the presentation into batches before submitting again. |
401 |
unauthorized |
Missing API key, or the format of the Authorization header is incorrect. |
Ensure the header format is Authorization: Bearer <YOUR_API_KEY>. |
402 |
insufficient_quota |
Credit or Spark quota within the workspace has been exhausted. | Prompt the user to log in to the DeckFlow settings page to top up or upgrade their plan. |
403 |
forbidden |
The API key is valid, but lacks permission to access the current workspace, feature, or target Space. | Verify that the spaceId parameter is correct and inspect the permissions associated with your API key. |
429 |
rate_limit_exceeded |
Concurrent API calls have exceeded rate limit thresholds. | Implement client-side Exponential Backoff retries to reduce request concurrency. |
5xx |
internal_error |
Internal server error or temporary network issue. | Retry using a backoff strategy. |
Task Retry Strategy
When handling responses from the DeckFlow back-end in your applications, please follow this retry logic:
- Retryable Errors:
- HTTP
429(Rate Limit): Wait and perform an exponential backoff retry. - HTTP
5xx(Temporary Server Failure): Recommended to automatically retry after a short delay.
- HTTP
- Non-Retryable Errors:
- HTTP
400/401/403: Typically parameter, authentication, or permission issues. Repeating the request will yield the same result. You must fix the parameters or permissions before retrying. - HTTP
402(Insufficient Quota): Requires the user to top up or purchase additional quota before retrying.
- HTTP