Errors

Error bodies and status codes for every Landbot API, what each one means and which ones to retry.

Every Landbot API answers an error with a 4xx or 5xx status and, most of the time, a JSON body. The shape of that body depends on the API and on where the request was stopped.

Check the status code first

Branch on the status code, then read the body. A 404 or a 5xx always arrives as an HTML page, whatever the Accept header says, so parse the body only when Content-Type says it is JSON:

const res = await fetch(url, { method, headers, body });
if (!res.ok) {
  const type = res.headers.get("content-type") || "";
  const detail = type.includes("json") ? await res.json() : await res.text();
  throw new Error(`HTTP ${res.status}: ${JSON.stringify(detail).slice(0, 200)}`);
}

Error bodies

Platform API

The Platform API uses two shapes.

A per-field map, for validation and state errors the endpoint checks itself (400, 402, 403, 412, 422):

{
  "errors": {
    "customer_id": ["The customer is blocked"]
  }
}

A single detail string, for requests stopped before the endpoint runs: a missing or bad token (401), a body that isn't valid JSON (400), a wrong method (405) and rate limiting (429):

{
  "detail": "Invalid token."
}

A customer, channel or hook that belongs to another workspace answers 404, the same as one that doesn't exist.

APIchat

Errors the endpoint checks itself (409 and 422) use success and a single error string:

{
  "success": false,
  "error": "Invalid message type"
}

Everything else uses detail, the same as the Platform API. That includes a missing, wrong or inactive channel token, which answers 403:

{
  "detail": "Invalid token."
}

POST /file/{customer_token}/ reports validation errors as a per-field map under errors.

Bots API, AI Agents API and Channels API

The Bots API answers named refusals as {"error": {"code": "...", "message": "..."}}. See When a call fails for every code. The AI Agents and Channels APIs document their error bodies on each operation in the AI Agents API and Channels API references.

On all three, a 404 or 5xx currently arrives as the HTML page described in Check the status code first, not with those JSON bodies. Branch on the status code before you read error.code.

Status codes

A 402 body names the cause. An expired subscription answers {"errors": {"brand_id": ["Payment required"]}}. A plan without the feature answers <plan> required under brand_id, naming one of the plans listed under plans that include the feature.

On the Platform API, the only 403 from a role is {"errors": {"token": ["You don't have enought permissions"]}}. The agent token acts as its agent, so ask an admin to give that agent's role the permission, or use the token of an agent who has it.

412 Precondition Failed

A 412 body is a per-field map, and each request reports one cause at a time.

send_* covers send_text, send_image, send_location and send_template. Sending to an unassigned customer assigns them to the token's agent, so a second agent's token gets The customer is assigned to other agent from then on.

Trailing slash

Every Platform API and APIchat path ends with /. A request without it is redirected with a 301 to the same path with the slash. Most HTTP clients follow that redirect as a GET and drop the body, so a POST without the slash fails in confusing ways. Write the slash.

Retries

• Retry 429 and 5xx without changing the request. Wait for Retry-After on a 429 (or back off when it is missing), and back off exponentially with jitter on a 5xx.
• Retry 412 once the state it names has changed.
• Fix the request before retrying 400, 404, 405, 409, 413 and 422.
• Fix the token, the role or the plan before retrying 401, 402 and 403.

async function call(url, options, attempts = 5, maxWaitSeconds = 60) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, options);
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || i === attempts - 1) return res;
    const retryAfter = Number(res.headers.get("retry-after"));
    if (retryAfter > maxWaitSeconds) return res;
    const wait = retryAfter > 0
      ? retryAfter * 1000
      : Math.min(2 ** i * 100, 5000) + Math.random() * 100;
    await new Promise(r => setTimeout(r, wait));
  }
}

Duplicate requests

No Landbot API takes an idempotency key. A POST that times out on your side may or may not have run, and retrying it can send the same message twice.

Most state changes on the Platform API are PUT requests (archive, block, assign), and repeating one leaves the same state. For the send endpoints, decide whether a possible duplicate is worse than a possible gap, and retry only when it isn't.