Learn how RenderIO reports errors - HTTP status codes, validation errors, command failures, and webhook delivery failures.

Error Handling

RenderIO uses standard HTTP status codes and consistent error response formats. This page covers every type of error you may encounter and how to handle each one.

HTTP status codes

Code	Meaning	When it occurs
`200`	Success	Successful GET, PUT, or DELETE requests
`201`	Created	Resource successfully created (e.g., new preset)
`404`	Not Found	Command, file, or preset does not exist or does not belong to your account
`422`	Validation Error	Request body is malformed or contains invalid values
`500`	Server Error	Unexpected internal error

Validation errors (422)

When your request body fails validation, RenderIO returns a 422 response with a detail array describing each problem:

{
  "detail": [
    {
      "loc": ["input_files"],
      "msg": "input_files is required and must be a non-empty object",
      "type": "value_error"
    },
    {
      "loc": ["ffmpeg_command"],
      "msg": "ffmpeg_command is required and must be a string",
      "type": "value_error"
    }
  ]
}

Each error object contains:

Field	Description
`loc`	Path to the field that failed validation (e.g., `["input_files", "in_video"]`)
`msg`	Human-readable description of the problem
`type`	Error category: `"value_error"` for invalid values, `"type_error"` for wrong types

Common validation errors include:

Missing required fields (input_files, output_files, ffmpeg_command)
Invalid alias prefixes (input keys not starting with in_, output keys not starting with out_)
Invalid alias characters (must match /^[a-zA-Z0-9_]+$/)
Too many commands in a chained or multiple request (max 10)
Too many metadata properties (max 10)
Invalid URL format for webhook_url or file_url

Command failures

A command can be accepted successfully (HTTP 200) but still fail during processing. When this happens, the command status becomes FAILED and two fields describe the error:

{
  "command_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "FAILED",
  "error_status": "FFMPEG_ERROR",
  "error_message": "Unrecognized option 'invalid_flag'.",
  "original_request": { ... }
}

Field	Description
`error_status`	Error category code
`error_message`	Detailed error message, often including FFmpeg stderr output

Common causes of command failures:

Cause	Description
Invalid FFmpeg command	Syntax errors, unrecognized options, or incorrect filter usage
Input file unreachable	The URL in `input_files` returned a 404, timed out, or is not publicly accessible
Timeout exceeded	FFmpeg did not finish within the timeout determined by your subscription plan
Out of disk space	Output files exceed the available sandbox storage
Unsupported codec	The requested codec is not available in the FFmpeg build

File processing failures

Files stored via POST /api/v1/files/store-file or uploaded via POST /api/v1/files/upload can also fail during processing. When this happens, the file status becomes FAILED:

{
  "file_id": "a1b2c3d4-...",
  "status": "FAILED",
  "error_status": "DOWNLOAD_ERROR",
  "error_message": "Failed to download file: HTTP 403 Forbidden"
}

Common causes include the source URL being inaccessible, returning an error, or the file being corrupted.

Webhook delivery failures

When RenderIO cannot deliver a webhook to your configured URL, it retries with exponential backoff:

Attempt	Delay before retry
1	Immediate
2	5 seconds
3	5 minutes
4	30 minutes
5	2 hours
6	5 hours
7	10 hours
8	10 hours

After 8 consecutive failures, the webhook configuration is automatically disabled. You can re-enable it by updating your webhook config via PUT /api/v1/webhook-config.

A webhook delivery is considered failed if:

Your endpoint returns a non-2xx HTTP status code
Your endpoint does not respond within 15 seconds
The connection cannot be established

Best practices

Always check command status

Never assume a command succeeded. Always check the status field when polling:

const data = await pollCommand(commandId, apiKey);

if (data.status === "FAILED") {
  console.error(`Command failed: ${data.error_status} - ${data.error_message}`);
  // Handle the failure
} else if (data.status === "SUCCESS") {
  // Process the output files
  const outputFiles = data.output_files;
}

data = poll_command(command_id, api_key)

if data["status"] == "FAILED":
    print(f"Command failed: {data['error_status']} - {data['error_message']}")
    # Handle the failure
elif data["status"] == "SUCCESS":
    # Process the output files
    output_files = data["output_files"]

Validate FFmpeg commands locally

Before sending commands to RenderIO, test them locally with FFmpeg to catch syntax errors early:

# Test your command locally first
ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4

Handle both HTTP errors and command failures

Your integration should handle two layers of errors:

HTTP-level errors (4xx, 5xx) - the request itself failed
Command-level failures - the request succeeded but processing failed

async function runCommand(payload, apiKey) {
  const response = await fetch("https://renderio.dev/api/v1/run-ffmpeg-command", {
    method: "POST",
    headers: {
      "X-API-KEY": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  // Layer 1: HTTP errors
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`HTTP ${response.status}: ${JSON.stringify(error)}`);
  }

  const { command_id } = await response.json();

  // Layer 2: Command processing errors
  const result = await pollCommand(command_id, apiKey);
  if (result.status === "FAILED") {
    throw new Error(`Processing failed: ${result.error_message}`);
  }

  return result;
}

Inspect validation errors programmatically

The loc field in validation errors tells you exactly which field is problematic, making it straightforward to surface errors in a UI or log them:

if (response.status === 422) {
  const { detail } = await response.json();
  for (const error of detail) {
    console.error(`Field ${error.loc.join(".")}: ${error.msg}`);
  }
}

Polling & Webhooks -- set up result delivery with retry handling
Webhook Payload reference -- payload format and signature verification

Error Handling

On this page