Errors

Error response format

Most error responses return a JSON body with an error field:

{
  "error": "<message>"
}

Some endpoints return a plain-text message body instead of JSON. Check the Content-Type response header when parsing errors programmatically.

HTTP status codes

Status	Meaning
`200 OK`	Request succeeded.
`400 Bad Request`	Invalid parameters or missing required fields.
`401 Unauthorized`	Missing, invalid, or insufficient API key.
`403 Forbidden`	Your plan does not include this feature.
`404 Not Found`	Resource does not exist or does not belong to your account.
`429 Too Many Requests`	Rate limit exceeded (100 requests per 2-minute window).
`500 Internal Server Error`	Unexpected server error.

Common errors

401 — Missing API key

The Authorization header is absent or does not start with Bearer .

"Missing API key"

Add the header to your request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.demomatic.tech/v1/videos

401 — Invalid API key

The key in the Authorization header does not match any active key on your account.

"Invalid API key"

Verify that the key is copied correctly and has not been deleted. You can manage your keys in Settings > API Keys.

401 — Invalid permissions

The key has read_only permission but the request uses a write method (POST, PUT, or DELETE).

"Invalid permissions"

Either switch to a GET request or use an all_access key.

403 — Plan does not include API access

The account associated with the API key is not on a Starter or Growth plan.

"Your plan does not include API access"

Upgrade your plan to enable API access.

404 — Resource not found

The requested resource does not exist, or it belongs to a different account.

# Example: video ID that doesn't exist or belongs to another account
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.demomatic.tech/v1/videos/99999
# → 404

Confirm the ID is correct and that the resource was created under the same account as your API key.

429 — Rate limit exceeded

You have sent more than 100 requests in a 2-minute window from the same IP address.

"Too many requests from this IP, please try again later."

Wait before retrying. Implement exponential backoff to avoid hitting the limit repeatedly.

Handling errors in code

const response = await fetch('https://api.demomatic.tech/v1/videos', {
  headers: { Authorization: `Bearer ${process.env.DEMOMATIC_API_KEY}` },
});

if (!response.ok) {
  const body = await response.text();
  // Parse JSON error if available, otherwise use plain text
  let message;
  try {
    message = JSON.parse(body).error ?? body;
  } catch {
    message = body;
  }
  throw new Error(`Demomatic API error ${response.status}: ${message}`);
}

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

import os, requests

response = requests.get(
    "https://api.demomatic.tech/v1/videos",
    headers={"Authorization": f"Bearer {os.environ['DEMOMATIC_API_KEY']}"},
)

if not response.ok:
    try:
        message = response.json().get("error", response.text)
    except ValueError:
        message = response.text
    raise Exception(f"Demomatic API error {response.status_code}: {message}")

data = response.json()["data"]

For 429 responses, read the Retry-After header if present, or implement exponential backoff starting at 1 second.

Overview

Videos

Domains

Error response format

HTTP status codes

Common errors

Handling errors in code

​Error response format

​HTTP status codes

​Common errors

​Handling errors in code

Error response format

HTTP status codes

Common errors

Handling errors in code