When a call fails

Check the status, then read the shape that goes with it.

Four shapes

Shape You get it for
{"error": {"code": …, "message": …}} A refusal with a name. 404, 422, 502. code is the one thing safe to branch on
{"error": "<message>"} Something not built yet. 501
{"detail": "<message>"} You were stopped before the call got in. 401, 403, 405, 429
{"<field>": ["<reason>"]} Your body or query string could not be read. 400

A 422 about a diagram carries violations as well, listing what is wrong and which block it is about.

The statuses

  • 400 — we could not read what you sent. Keyed by the field at fault, or non_field_errors when no single field is.
  • 401 — no credentials, or credentials that name nobody.
  • 403 — you are signed in and may not do this. Four different things answer this and the body does not say which: your role lacks the permission; an OAuth token lacks a scope the call needs, such as scripts:write to add a Code, Code set or Google analytics block or change its script; the brand is disabled or locked; the subscription has expired and you tried to write.
  • 404 — no such bot, or not yours. The two answer identically. A connected account answers the same way, and one that was revoked, that the app asks to reconnect, or whose credential Google no longer takes, answers as if it were not there. So does a connection: no such connection, or not yours. So does a test conversation: no such conversation, one held with another bot, or a chat that is not a test conversation at all.
  • 405 — the path exists, the method does not.
  • 409: a test conversation asked of a web or WhatsApp bot whose draft was never deployed for testing: there is no test copy to talk to yet. Deploy the draft first. On a WhatsApp bot, also one asked where no WhatsApp number can play the visitor (whatsapp_test_visitor_unavailable), including one that would not stay silent: a bot of its own answers it, or it is Landbot's WhatsApp testing number itself.
  • 422 — we understood you and refused. Either a value we do not accept, or a diagram that breaks rules, or a spreadsheet Google will not read through the account you named, or a file we do not keep as media. In a WhatsApp bot's test conversation, also a button tapped (taps_not_offered_on_whatsapp): Meta lets no business send a tap, and typing the option's text reaches the block's default output instead of the option.
  • 429 — too many requests. Every call counts, reads included. Uploading media is also counted per brand, 60 uploads an hour shared by every member.
  • 501 — described here, not built yet.
  • 502 — something we depend on failed. Retrying is reasonable.

Refusals that carry a code

bot_not_found · version_not_found · block_not_found · workspace_not_found · bot_name_not_accepted · channel_family_not_readable · bot_not_in_the_trash · builder_version_not_supported · diagram_beside_a_source · draft_has_violations · restored_draft_has_violations · version_of_an_unsupported_builder · version_is_the_most_recent_publication · diagram_compilation_failed · connected_account_not_found · google_spreadsheets_failed · spreadsheet_not_readable · connection_not_found · media_type_not_accepted · media_too_large · test_conversation_not_found · test_conversations_not_offered · test_copy_not_deployed · whatsapp_test_visitor_unavailable · taps_not_offered_on_whatsapp

Rules a diagram can break

Each one is a code in a violation. A code you get that is not listed here came from a bot an older builder wrote, or from a rule the compiler added after this page, and is passed through rather than invented.

A rule broken inside a brick names its block by the trail that reaches it: B0->n0 is the block n0 inside the brick placed by the block B0, and B0->B1->n3 is one level further down.

Refused on the spot

These answer 422 and store nothing, because there would be nothing sensible to store.

  • block_unknown — the block is of a type we do not describe.
  • block_id_taken — the id you gave a new block already names one in the diagram. For a block that runs a brick, it is also the id of a block inside a brick the document keeps. Inside a brick you write, it is also an id that brick already holds, outputs, or an id the document keeps a brick under.
  • block_not_in_draft — you named a block for update or delete that the draft does not hold. Only PATCH /bots/{bot_id}/draft reports it; the single-block endpoints answer 404.
  • block_params_undescribed — the params leave us unable to say which block it is.
  • param_output_id_invalid — something you derive an output from has an id that cannot be one: a button payload not starting with $. Names it in param.
  • param_output_id_duplicated — something you derive an output from has the id an item before it already has, such as two buttons with one payload or a status code listed twice, so both would be one output and the later one could lead nowhere of its own. Names the later one in param.
  • param_formula_not_compiled — the formula does not compile.
  • param_buttons_not_matched — an ask_scale block's buttons carry texts that are not the numbers from fromValue to toValue, so the visitor would be shown a scale other than the block's range. Leave buttons out and they are written from the range. Names buttons.
  • param_range_too_long — an ask_scale block's fromValue and toValue span more than 100 numbers. Names toValue.
  • linked_bot_not_found — a bot_link block names by uuid a bot it cannot jump to: not one of the brand's, in the trash, or built with an older builder. Any write can answer it, a whole diagram included, since a uuid is never stored. Names botID in param.
  • connection_output_removed — your change takes away an output a connection still leaves from. Names those connections in connections.
  • connection_block_removed — you added a connection to a block the same change set deletes.
  • block_not_a_brick — you sent a brick for a block that runs none.
  • brick_nesting_unsupported — a block inside a brick you write runs a brick of its own. The builder nests bricks, and a nested brick it wrote is read and judged; this API does not write one.
  • brick_output_unknown — a connection inside a brick you write ends at outputs.$N, and the brick declares no output $N.

Inside a brick you write, block_unknown, block_id_taken, param_output_id_invalid, param_output_id_duplicated, param_formula_not_compiled, param_buttons_not_matched, param_range_too_long, connection_output_unknown and connection_target_not_allowed are refused the same way, and name the block by its trail.

Stored, and reported back

Everything below is saved with your draft. You keep editing; you cannot publish or test until they are gone.

Four of them cut both ways. entry_node_of_another_channel, connection_output_unknown, connection_target_not_allowed and brick_missing are stored when a whole-diagram write puts them there, and refused on the spot when you add or edit the block or the connection that causes them — POST /bots/{bot_id}/draft/blocks is where an id is chosen, the block-level writes are where an output and a connection are, and where a brick comes with what it holds.

The block the bot starts from

  • start_connection — the diagram holds neither the greeting node nor the start point.
  • welcome_block_not_allowed — the block in the greeting slot cannot be a greeting. can_be_welcome in GET /blocks says which can. On whatsapp the slot takes any block but a note, global keywords or the inactivity trigger, which the bot is compiled without.
  • welcome_version_invalid — the greeting does not carry version: 3. landbot bots only. We add the marker when you add the block, so what is left to report is a version you sent yourself, and PUT /bots/{bot_id}/draft, which stores the diagram as it is sent.
  • entry_node_of_another_channel — a node uses another channel family's greeting id: welcome on a bot that is not landbot, or bot_start on one that is. Refused on the spot when you add the block.

Where the bot runs

  • block_not_on_channel — the block does not run on the bot's channel family. channel_restriction in GET /blocks says which families each variant runs on; empty means all of them.

Wiring

  • connection_wrong — a connection points at a block the diagram does not contain. One leaving from a block the diagram does not contain is not reported: a connection is only read from the block it leaves, so nothing reads it.
  • connection_output_unknown — a connection leaves from an output its block does not have. Refused on the spot when you add or edit that block. A brick has the outputs its outputs node lists, and default.
  • connection_target_not_allowed — a connection ends at a note, at global keywords or at the inactivity trigger. The bot is compiled without any of them, so the connection leads nowhere. Names the block it leaves, and is refused on the spot when you add the connection.
  • bot_loop — blocks that never wait for an answer form a closed loop, so the conversation never reaches the person. A brick waits for an answer when a block inside it does.

Bricks

  • brick_missing — a brick block whose brick the document does not keep: there is nothing in bricks under the block's id, so the block has nothing to run. Refused on the spot when you add or edit the block without its brick.
  • brick_start_missing — the brick holds no block under the id brick_start, which is where it starts. A brick the builder has just created is like this, which is why it is stored.
  • brick_start_not_allowed — the block under brick_start is a note, global keywords or the inactivity trigger, which the bot is compiled without, so nothing leads into the brick. Names that block by its trail.
  • brick_outputs_missing — the brick holds no outputs node, so nothing says which outputs it is left by, and the connections leaving it are not judged.
  • brick_nested_in_itself — a block inside a brick places one of the bricks it sits in, directly or through another brick, so that brick would run inside itself. Names that block by its trail.
  • brick_level — bricks nested deeper than allowed. Names the block too deep by its trail, the longest one when several reach it.

The inactivity trigger

  • inactivity_id_fixed — an inactivity block under an id other than inactivity, which is the only one it takes and the one it is given when none is sent.
  • inactivity_id_reserved — a block other than the inactivity trigger holds the id inactivity.
  • inactivity_in_brick — an inactivity block inside a brick. The trigger belongs to the bot, so it is placed at the top of the diagram only. Names the block by its trail.

One param, named in param

  • param_required — missing.
  • param_invalid_type — wrong type.
  • param_no_matching_shape — matches none of the shapes declared for it. GET /blocks has them.
  • param_non_empty — empty where it may not be.
  • param_invalid_format — does not match the pattern in GET /blocks.
  • param_forbidden_format — matches a pattern it must not.
  • param_too_long — longer than max_length.
  • param_too_many_items — a list carrying more items than max_items. When the rule names a field, the items carrying true under it are headings and are not counted.
  • param_heading_not_first — a list carrying headings, the items marked by the rule's field, that does not open with one.
  • param_not_lowercase — carries a capital letter or whitespace where the runtime only matches a value lowercased and split on whitespace: a button's payload on buttons, reply_buttons, ask_yes_no, ask_rating, ask_scale, ask_picture_choice and ask_autocomplete.
  • param_not_allowed — not one of the enum values.
  • param_reserved — a value the block keeps for itself.
  • param_unknown_function — a formula calls a function the block does not know.
  • param_invalid_json — has to be JSON and does not parse.
  • param_format_not_matched — an ask_date block's format does not start with the pattern of its pickerFormat, or of yyyy/MM/dd when it has none, so the date picked is refused or read with day and month swapped. Names format.
  • connected_account — names an account that is not connected to the bot's brand. Checking it takes a lookup, so it is checked only when you create a bot with a diagram, deploy, publish or restore a version, and never on a draft write: the next write clears it until the next deploy finds it again.
  • connection_bot — a bot_link block names by number a bot that is not one of the brand's, or is in the trash. Names botID in param. Checked when an account is, on the same four paths.
  • connection_wrong on a bot_link block — the bot it jumps to has no published block where the jump enters it. Names nodeID when the block picks one. When it enters at the start, it names botChannelFamily if the target has published the other family's start, so the family written is not the target's; and it names no param if the target has published no greeting at all, as a bot created through this API is born with its greeting slot empty: pick a block, or give the target a greeting and publish it. Checked on the same four paths, against what the target has published, since that is what the conversation reaches.
  • goal_no_id — a goal block names by number a goal that is not one of the brand's, so the conversions it counts would show nowhere. Names goal in param. Checked when an account is, on the same four paths; null is the bot's default goal and is never looked up.

Found by the compiler

The compiler that turns the diagram into what the runtime runs refuses a few diagrams itself. It is only reached when you create a bot with a diagram, deploy, publish or restore a version, so like connected_account these are found on those four paths and never on a draft write: creating stores nothing, and the next write clears them until the next deploy finds them again. The codes are the compiler's own, lowercased, so one it adds later reaches you the same way. Today there are three: welcome_node_missing when the start point of a landbot bot is connected to no welcome block, naming start_point; welcome_node_invalid when the block in the welcome slot cannot start a conversation, such as a node whose template names no block, naming welcome; and webhook_response_path_missing when a webhook block saves its response into a field without saying which part of the response to read, naming the block.

About storage rather than the diagram

  • block_is_not_valid — a violation was stored against the block with no readable code. Something is wrong with it; what, we cannot recover.

Warnings

A draft and a publication also carry warnings, shaped like violations. They refuse nothing: you can still save, test and publish.

  • block_not_on_v4_web_chat — the block shows something the v4 web chat does not render, which message names. landbot bots only. The legacy web chat renders it.