API Limits and Error Codes

Job Timeouts

FFmpeg jobs are subject to a maximum execution time.

• Default timeout: 5 minutes if timeout_seconds is not specified.
• Per-request override: Pass timeout_seconds on job creation to override the default timeout.
• Maximum duration: Accounts with less than $10 pre-paid balance may request up to 5 minutes. Accounts with $10 or more may request up to 6 hours.
• ?wait=true requests: Synchronous wait mode has a maximum timeout of 5 minutes regardless of account balance.
• When timeout is reached: If a job exceeds its timeout, the process is terminated and the job status is set to failed.
• Advice: The overwhelming majority of FFmpeg jobs handled by us finish in less than 5 minutes, the few jobs that exceed 5 minutes overwhelmingly involve faulty ffmpeg commands. For your convenience, we recommend using the 5 minute default timeout unless you are processing very large files (many GB) and/or using extremely computationally intensive filters.

Rate Limits

The API implements rate limiting to ensure fair usage across all customers.

• Scope: Limits apply per account across all endpoints.
• Default Limit: New accounts start at 10 requests per second.
• Increased Limit: Accounts with a pre-paid balance get 100 requests per second.
• When limit is hit: Requests over the limit are rejected with 429 Too Many Requests.

Handling Rate Limits

If you exceed your account limit, the API returns 429 Too Many Requests.

{
  "errorCode": "tooManyRequests",
  "message": "Rate limit exceeded"
}

Use retry logic with exponential backoff to avoid retry spikes.

Output file retention

• Output retention: Output files are retained for at least 30 days.
• Output URL lifetime: Signed output download URLs expire after 7 days. If your output URL expires, you can simply refetch the job to get a freshly signed URL.

Error Codes

Most failures return a stable errorCode value and a human-readable message.

Common Error Codes

• validationError: Request body or query input is invalid.
• badRequest: Request shape is valid JSON but business rules fail.
• badApiKey: API key is missing, invalid, or revoked.
• forbidden: Authenticated but not allowed for this resource.
• notFound: Requested resource does not exist.
• tooManyRequests: Rate limit exceeded.
• unknownError: Unexpected server-side failure.

Error Response Shape

{
  "errorCode": "validationError",
  "message": "Invalid order data"
}