API Limits and Error Codes

Job Timeouts

FFmpeg jobs are subject to a maximum execution time.

• Maximum Duration: 6 hours.
• Action: If a job exceeds this limit, the process is terminated and the job status is set to failed.
• ?wait=true requests: Synchronous wait mode times out after 15 minutes. If not completed in time, job is auto-cancelled.
• Output retention: Output files are retained for 30 days.
• Output URL lifetime: Signed output download URLs last 7 days.

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 and jitter to avoid retry spikes.

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"
}