Reference

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.