Error Handling

The Xora API uses consistent error responses across all endpoints. This guide covers the error format, common error codes, and best practices for handling failures.

Error response format

Every error response follows this structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong",
    "retryable": false
  }
}

Field	Type	Description
code	string	Machine-readable error code (always UPPER_SNAKE_CASE)
message	string	Human-readable explanation
retryable	boolean	Whether the request can be retried

Job-specific errors

When a job fails, the error also includes a stage field indicating where in the pipeline the failure occurred:

{
  "jobId": "01JXYZ...",
  "state": "failed",
  "error": {
    "code": "TRANSCODE_ERROR",
    "message": "FFmpeg exited with code 1: Invalid data found when processing input",
    "stage": "transcoding",
    "retryable": true
  }
}

Common error codes

HTTP errors (API layer)

Code	HTTP Status	Meaning
UNAUTHORIZED	401	Missing or invalid API key / session
NOT_FOUND	404	Job, preset, file, or resource not found
VALIDATION_ERROR	400	Request body failed schema validation

Processing errors (job failures)

Code	Meaning	Retryable
ENGINE_ERROR	Processing failure	Usually yes
ENGINE_INVOCATION_ERROR	Processing timed out or crashed	Yes
ENGINE_INVOKE_FAILED	Could not start the job	Yes
ENGINE_EMPTY_RESPONSE	No result was returned	Yes
ENGINE_INVALID_RESPONSE	Unexpected response format	Yes
CONFIG_ERROR	Server misconfiguration	No
UNSUPPORTED_COMMAND	FFmpeg args rejected by security validation	No
TRANSCODE_ERROR	FFmpeg processing failed	Sometimes

Validation errors

Scenario	Example message
Missing input URL	"input.url is required for this recipe"
Invalid output format	`“Invalid enum value. Expected ‘mp4'
Bad FFmpeg args	"ffmpeg.args must contain at least 1 element"
Concat with single file	"concat recipe requires input_files with at least two entries"
Mixed input modes	"Use either input/output or input_files/output_files, not both"
Invalid webhook URL	"webhookUrl must use https://"

Handling retryable errors

When retryable is true, you can retry the request. For job failures, use the retry endpoint:

cURL

curl -X POST https://api.xora.sh/v1/jobs/JOB_ID/retry \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const response = await fetch('https://api.xora.sh/v1/jobs/JOB_ID/retry', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs/JOB_ID/retry",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)

{
  "retried": true,
  "jobId": "01JXYZ1234ABCDEF56789000"
}

Note

You can only retry jobs in a terminal state: failed, rejected, or cancelled. Retrying re-runs the job with the original parameters.

Retry strategy for API calls

For transient API errors (5xx), use exponential backoff:

Node.js

async function callXoraApi(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) return response.json();

    const body = await response.json();

    // Don't retry client errors (4xx) — they won't succeed
    if (response.status < 500) throw new Error(body.error.message);

    // Retry server errors with exponential backoff
    if (attempt < maxRetries - 1) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw new Error('Max retries exceeded');
}

Python

import time
import requests

def call_xora_api(url, method="GET", max_retries=3, **kwargs):
    for attempt in range(max_retries):
        response = requests.request(method, url, **kwargs)

        if response.status_code < 400:
            return response.json()

        body = response.json()

        # Don't retry client errors (4xx) — they won't succeed
        if response.status_code < 500:
            raise Exception(body["error"]["message"])

        # Retry server errors with exponential backoff
        if attempt < max_retries - 1:
            delay = (2 ** attempt)  # 1s, 2s, 4s
            time.sleep(delay)

    raise Exception("Max retries exceeded")

Error responses by endpoint

POST /api/v1/jobs (create job)

Status	Code	When
400	VALIDATION_ERROR	Invalid request body
401	UNAUTHORIZED	Bad or missing auth
404	NOT_FOUND	Preset not found (when using presetId)
500	ENGINE_ERROR	Server failed to accept the job

GET /api/v1/jobs/:id (get job)

Status	Code	When
401	UNAUTHORIZED	Bad or missing auth
404	NOT_FOUND	Job doesn’t exist or belongs to another user
500	ENGINE_ERROR	Server unreachable

POST /api/v1/jobs/:id/cancel

Status	Code	When
401	UNAUTHORIZED	Bad or missing auth
404	NOT_FOUND	Job not found
500	ENGINE_ERROR	Server failed to cancel

DELETE /api/v1/jobs/:id/output

Status	Code	When
401	UNAUTHORIZED	Bad or missing auth
404	NOT_FOUND	Job or output not found

Best practices

Tip

1. Always check retryable — only retry when the error says it’s safe to do so.
2. Use exponential backoff — don’t flood the API with rapid retries.
3. Log the full error — the code, message, and stage fields together give you the complete picture.
4. Handle 401 early — if you get UNAUTHORIZED, check your API key before retrying.
5. Set up webhooks — webhook payloads include error details, so you can handle failures without polling.

Job failure stages

When a job fails, the stage field tells you where in the pipeline it broke:

Stage	What was happening
probing	Analyzing the input file
planning	Deciding how to process
segmenting	Preparing the input for processing
transcoding	Running FFmpeg
merging	Assembling the final output

This helps you diagnose whether the issue is with your input file, your FFmpeg command, or a transient server problem.