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, ornon_field_errorswhen 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 asscripts:writeto 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. OnlyPATCH /bots/{bot_id}/draftreports it; the single-block endpoints answer404. 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 inparam. -
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 inparam. param_formula_not_compiled— the formula does not compile.-
param_buttons_not_matched— anask_scaleblock'sbuttonscarry texts that are not the numbers fromfromValuetotoValue, so the visitor would be shown a scale other than the block's range. Leavebuttonsout and they are written from the range. Namesbuttons. -
param_range_too_long— anask_scaleblock'sfromValueandtoValuespan more than 100 numbers. NamestoValue. -
linked_bot_not_found— abot_linkblock 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. NamesbotIDinparam. -
connection_output_removed— your change takes away an output a connection still leaves from. Names those connections inconnections. connection_block_removed— you added a connection to a block the same change set deletes.block_not_a_brick— you sent abrickfor 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 atoutputs.$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_welcomeinGET /blockssays which can. Onwhatsappthe 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 carryversion: 3.landbotbots only. We add the marker when you add the block, so what is left to report is a version you sent yourself, andPUT /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:welcomeon a bot that is notlandbot, orbot_starton 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_restrictioninGET /blockssays 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 itsoutputsnode lists, anddefault. -
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— abrickblock whose brick the document does not keep: there is nothing inbricksunder the block's id, so the block has nothing to run. Refused on the spot when you add or edit the block without itsbrick. -
brick_start_missing— the brick holds no block under the idbrick_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 underbrick_startis 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 nooutputsnode, 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— aninactivityblock under an id other thaninactivity, 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 idinactivity.-
inactivity_in_brick— aninactivityblock 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 /blockshas them.param_non_empty— empty where it may not be.param_invalid_format— does not match thepatterninGET /blocks.param_forbidden_format— matches a pattern it must not.param_too_long— longer thanmax_length.-
param_too_many_items— a list carrying more items thanmax_items. When the rule names afield, the items carryingtrueunder it are headings and are not counted. -
param_heading_not_first— a list carrying headings, the items marked by the rule'sfield, 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 onbuttons,reply_buttons,ask_yes_no,ask_rating,ask_scale,ask_picture_choiceandask_autocomplete. param_not_allowed— not one of theenumvalues.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— anask_dateblock'sformatdoes not start with the pattern of itspickerFormat, or ofyyyy/MM/ddwhen it has none, so the date picked is refused or read with day and month swapped. Namesformat. -
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— abot_linkblock names by number a bot that is not one of the brand's, or is in the trash. NamesbotIDinparam. Checked when an account is, on the same four paths. -
connection_wrongon abot_linkblock — the bot it jumps to has no published block where the jump enters it. NamesnodeIDwhen the block picks one. When it enters at the start, it namesbotChannelFamilyif 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— agoalblock names by number a goal that is not one of the brand's, so the conversions it counts would show nowhere. Namesgoalinparam. Checked when an account is, on the same four paths;nullis 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, whichmessagenames.landbotbots only. The legacy web chat renders it.