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	API requires Business+, or video minutes exhausted
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 the 60 requests-per-minute limit. Wait for the window to reset. See Rate Limiting for details.

Limit exceeded (403)

Returned in two cases:

1. No API access - the REST API requires the Business plan or higher.

   {
     "error": {
       "code": "limit_exceeded",
       "message": "API access requires the Business plan or higher. Upgrade at /dashboard/billing."
     }
   }

2. Out of video minutes - you've used your monthly allowance. It resets at the start of your next billing cycle. See Plans & Limits.

   {
     "error": {
       "code": "limit_exceeded",
       "message": "Video minutes quota exceeded. Used 60 of 60 minutes this period. Quota resets at the start of your next billing cycle."
     }
   }

Internal errors (500)

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