Error Handling

All API errors return a consistent JSON envelope.

Error format

{
  "error": {
    "code": "error_code_here",
    "message": "Human-readable description"
  }
}

Error codes

Code	HTTP Status	Description
authentication_error	401	Invalid or missing API key
validation_error	400	Invalid request parameters
not_found	404	Resource does not exist
rate_limit_exceeded	429	Too many requests
limit_exceeded	403	Plan limit reached or feature not available
internal_error	500	Server error

Handling errors

Authentication errors (401)

Check that your API key is valid, not revoked, and included in the Authorization header with the Bearer prefix.

Validation errors (400)

The message field describes which parameter is invalid. Fix the request body or query parameters and retry.

{
  "error": {
    "code": "validation_error",
    "message": "Must be a video content type"
  }
}

Not found (404)

The requested resource doesn't exist or belongs to a different workspace.

Rate limit exceeded (429)

You've exceeded your plan's requests-per-minute limit. Wait for the window to reset. See Rate Limiting for details.

Limit exceeded (403)

Your plan doesn't include this feature (e.g., translation on Starter plan). Upgrade your plan to access it.

{
  "error": {
    "code": "limit_exceeded",
    "message": "Translation requires Growth plan or higher"
  }
}

Internal errors (500)

A server-side issue occurred. These are rare — retry after a short delay. If persistent, contact support.