Errors

Error shape

Every non-2xx response carries the same JSON envelope:

{
  "error": {
    "type": "not_found",
    "message": "Conversation kw3pq2nyax7lr9d does not exist."
  }
}

type is a stable machine-readable code. message is a human-friendly explanation that may change wording over time. Some errors include extra fields (e.g. rate limits include tier and upgrade_url).

Common types

• bad_request — request body or query parameters are malformed. 400.
• auth — the API key is missing or wrong. 401.
• forbidden — the key is valid but doesn't grant access to this resource. 403.
• plan_upgrade_required — the feature isn't included on the current plan. The body includes tier and upgrade_url. 403.
• meeting_bot_forbidden — the workspace has the meeting bot disabled. 403.
• not_found — the resource doesn't exist or the key can't see it. 404.
• rate_limited — too many requests in the current window. The body includes tier and upgrade_url on freemium. 429.
• internal_error — something broke on our end. Retry with backoff. 5xx.

Retrying

The official SDKs retry idempotent calls (every GET) on 5xx and 429 with exponential backoff. They never automatically retry 4xx errors other than rate limits — those represent a caller bug to fix, not a transient failure.

If you're rolling your own client, treat any 5xx as retriable, respect the Retry-After header on 429, and stop after a few attempts to avoid drowning a degraded backend.