Filestack Error Diagnosis

Security Policy Errors (403)

403s from security-enabled apps are usually one of:

1. Expired policy — expiry unix timestamp is in the past

   import time
   policy = { "expiry": int(time.time()) + 3600, "call": ["read"] }  # 1 hour from now
   

2. Wrong signature — HMAC computed with wrong secret, or policy was modified after signing

   • Re-generate both policy and signature together — never modify the policy JSON after signing

3. Insufficient call scope — policy doesn't include the operation being performed

   • read for CDN delivery, store for upload, convert for transformations, remove for delete

4. Wrong CORS origin — browser request blocked

   • Filestack dashboard → your app → Security → add your domain

Transformation Errors

Diagnosis Checklist

Run through this in order when debugging Filestack errors:

1. API key valid? — Try a simple retrieve call: GET https://www.filestackapi.com/api/file/<handle>/metadata?key=<apikey>
2. Policy not expired? — Decode the base64 policy and check the expiry field is in the future
3. Handle exists? — Retrieve metadata for the handle; 404 means handle is gone
4. CORS origin whitelisted? — Check Filestack dashboard → app → Security → Domains
5. Transform params valid? — Run the CDN URL in a browser; the error is often self-describing
6. Rate limit hit? — Check for 429 and Retry-After header in your HTTP client logs