Errors

Error envelope

All errors return JSON in this exact shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Required at messages.0.userId"
  }
}

• code is a stable, machine-readable string. New codes may be added; existing codes won't change semantics.
• message is human-readable and may include the failing field path or a short explanation. It's not stable — log it but don't pattern-match on it.

Successful responses (200, 202) never include an error field.

Status codes

Status	Code	Meaning	What to do
400	validation_failed	Body failed schema validation. message includes the failing field path.	Fix the payload, do not retry as-is.
401	invalid_credentials	Missing or malformed Authorization header, or unrecognized key.	Verify the key is correct and not revoked.
403	subscription_inactive	Key is valid but the user's API subscription has lapsed.	Resubscribe at /account; existing keys then start working again.
404	not_found	Export ID doesn't exist or doesn't belong to your key.	Don't retry — the ID is wrong.
413	validation_failed	Request body exceeded 10 MB.	Host images and pass URLs instead of data URLs.
500	internal_error	Something on our side. The render record is marked failed.	Retry with exponential backoff; if it persists, email us.

Retrying

Status	Retry?	Strategy
400	No	Fix the body.
401 / 403	No	Resolve the auth issue.
404	No	Bad ID.
429	Yes	Honor Retry-After. Returned when per-minute rate limits are exceeded. Will also be returned for monthly cap excess once that's enforced.
500	Yes	Exponential backoff: 1s, 2s, 4s, up to 3 attempts. Beyond that, surface the failure to the caller.

For video renders specifically, a failed status from GET /exports/:id means the Lambda render hit an unrecoverable error. You can re-submit the same payload to start a fresh render — failed renders don't count against your usage if we ever start enforcing quotas.