Errors

All error responses are JSON: { "error": "<message>", ...optional fields }.

HTTP status codes

Status	Meaning	Recovery
400	Validation error	Fix the request body. The error message names the offending field.
401	Missing or invalid API key	Re-check the Authorization header. Verify the key is active.
402	Insufficient credits	Top up. Response includes credits_required and credits_remaining.
403	Missing required scope	Create a new key with the required scope, or use a key that already has it.
404	Resource not found	Verify the job_id. Jobs older than ~30 days may be evicted.
409	Conflict	E.g. cancelling a job that already completed.
429	Rate limit exceeded	Back off. Honor Retry-After header (seconds).
500	Internal error	Retry with exponential backoff. If persists, file an issue.
502	Provider (fal.ai) error	Submission failed; credits already refunded. Inspect the message and retry.

Common 400 messages

• prompt is required (non-empty string)
• prompt too long (max 4000 chars)
• duration_seconds must be one of 4, 5, 6, 8, 10, 15
• aspect_ratio must be one of 16:9, 9:16, 1:1, 4:3, 3:4, 21:9
• resolution must be one of 480p, 720p
• image_url must be a https URL
• fast mode supports text-to-video only (no image_url)
• image_urls items must be https URLs
• num_images must be 1-4
• Invalid JSON body

Common 401 messages

• Missing Authorization header (Bearer cw_live_...)
• Invalid or revoked API key

402 details

{
  "error": "Insufficient credits",
  "credits_required": 75,
  "credits_remaining": 30
}

Recovery: top up credits in Dashboard → Billing, then retry.

Refund semantics

Credits are deducted before submitting to the provider. If submission fails, credits are automatically refunded to your balance and the API returns 502. You don't need to claim a refund.

If a job is cancelled (via DELETE /api/v1/jobs/:id), the full credit cost is refunded.

If a job completes successfully, no refund — you got the result.

If a job fails after submission (provider crash, timeout), background polling marks it as failed and refunds credits. Subsequent GET /api/v1/jobs/:id will show status: "failed" and error: "...".

Idempotency

API requests are NOT yet idempotent. If a POST /generate request times out from your side after the server already submitted to fal, you may double-charge. To detect this, check GET /api/v1/jobs/:id with the job_id from the earlier response (if you received one).

Idempotency keys (Idempotency-Key header) are on the roadmap.