Errors and limits

One error shape for every endpoint, the codes you can get, and the rate limits.

​

Error shape

Every error has the same body:

{
  "error": {
    "code": "limit_reached",
    "message": "2K video is not included in your plan.",
    "details": { "limit_code": "render_2k" }
  }
}

Branch on code, show message to people, and read details when it’s there.

​

Codes

Status	code	Meaning
400	invalid_request	The request body or a parameter is wrong. details names the field.
401	unauthorized	No API key, or the key is unknown or revoked.
402	paid_plan_required	The organization isn’t on a paid plan.
402	limit_reached	A plan limit is reached. details.limit_code says which.
403	forbidden	The key’s owner isn’t allowed to do this.
404	not_found	No such demo, question or endpoint in this organization.
409	conflict	The demo can’t change any more, a request with this idempotency_key is still running, or a webhook endpoint with this URL already exists.
410	gone	The question was already answered or has expired.
422	needs_answers	The task needs answers first. See questions.
422	not_feasible	The task can’t be recorded as written. message says why.
422	login_not_accepted_here	An assistant tried to send a login or code. details.answer_url is where a person can enter it.
429	rate_limited	Too many requests. Wait for the Retry-After header.
503	unavailable	Demosmith is busy or the API is paused. Try again shortly.

​

Rate limits

What	Limit
All requests, per API key	300 per minute
POST /demos and POST /demos/check	20 per minute

Assistants share the same limits. A 429 comes with a Retry-After header in seconds.

​

Retrying safely

• GET requests are always safe to retry.
• Add an idempotency_key to POST /demos. Sending the same key again returns the first demo (200) instead of creating another.
• Retry 429 and 503 after a short wait. Don’t retry 4xx errors without changing the request.