Use when user encounters Filestack API errors. Activates on: domain tokens (filestackapi.com, filestackcontent.com, process.filestackapi.com), error shapes ({'result': 'error', 'error':, {'error':, result: null in Filestack context), HTTP 401/403/404/429 from Filestack endpoints, or when user pastes a Filestack API error message.
Filestack APIs return errors in two formats:
v1 API format (api.filestackapi.com):
{ "result": "error", "error": { "code": 403, "msg": "Policy required" } }
Processing/CDN format (process.filestackapi.com, cdn.filestackcontent.com):
{ "error": "Unsupported conversion", "result": null }
| Code | Meaning | Likely Cause | Fix |
|---|---|---|---|
| 401 | Unauthorized | Invalid or missing API key | Check FILESTACK_API_KEY is correct and hasn't been rotated |
| 403 | Forbidden | Security policy violation, or CORS origin not whitelisted | See policy errors below |
| 404 | Not Found | Handle doesn't exist, has been deleted, or has expired | Verify handle is correct; check app's handle expiry setting |
| 429 | Rate Limited | Too many requests | Respect Retry-After header; implement exponential backoff |
| 500/502/503 | Server Error | Transient Filestack service issue | Retry with backoff; check status.filestack.com |
403s from security-enabled apps are usually one of:
Expired policy — expiry unix timestamp is in the past
import time
policy = { "expiry": int(time.time()) + 3600, "call": ["read"] } # 1 hour from now
Wrong signature — HMAC computed with wrong secret, or policy was modified after signing
Insufficient call scope — policy doesn't include the operation being performed
read for CDN delivery, store for upload, convert for transformations, remove for deleteWrong CORS origin — browser request blocked
| Error | Cause | Fix |
|---|---|---|
| "Unsupported input format" | Input file format not supported by the transform | Check Filestack docs for supported input formats per transform |
| "Output size limit exceeded" | Result would be larger than the app's output limit | Reduce target dimensions or use progressive encoding |
| "Processing timeout" | Transform took too long (usually video) | Use async transforms with a callback URL for video |
| "Invalid parameter" | Wrong parameter name or value type | Check CDN URL syntax: param:value (colon, not =) |
Run through this in order when debugging Filestack errors:
GET https://www.filestackapi.com/api/file/<handle>/metadata?key=<apikey>expiry field is in the futureRetry-After header in your HTTP client logs