Limits and errors

Our rule is show, never silently drop. When part of your content is still useful, we trim it and say so. When the shape is wrong, we reject it loudly. Nothing ever disappears without a note in your delivery log.

Limits

Limit	Value	What happens
Payload size	256 KB	Rejected — `PAYLOAD_TOO_LARGE` (HTTP `413`)
Messages per call	10	Rejected — `TOO_MANY_MESSAGES`
Blocks per message	25	Trimmed, plus a visible “+N more” block
Characters per `text` block	12,000	Trimmed, with a visible note
Buttons per `button_group`	5	Block removed — `BUTTONS_TOO_MANY`
Buttons per `card`	3	Block removed
Interactive blocks per message	5	Extras removed
Forms per message	1	Extras removed — `FORM_EXCLUSIVITY`
Fields per form	10	Block removed
Options per select	50	Block removed
Cards per message	5	Extras removed
Button `value` length	2,000 chars	Button removed
Message `metadata`	2 KB	Metadata removed; blocks still show
URL length	2,048 chars	Block removed
Updates per message	60	`429 UPDATE_LIMIT_REACHED`
Response URL lifetime	45 minutes	`410 RESPONSE_URL_EXPIRED`
Image upload	10 MB	`413 FILE_TOO_LARGE`
File upload	25 MB	`413 FILE_TOO_LARGE`

Two kinds of failure

Tier 1 — the whole payload is rejected

Nothing shows. The whole body is wrong: not JSON, an unknown shape, a bad version, too big, or too many messages. You get a 422 (or 413).

Tier 2 — one block is wrong

The message still goes through. The bad block shows as a small placeholder in the app, and is skipped on public pages. Everything else draws as normal.

That split is on purpose: one bad button should never cost your customer the whole answer.

The error body

{
  "ok": false,
  "error": {
    "code": "BLOCK_VALIDATION_FAILED",
    "message": "2 issue(s) found in your Block Kit payload.",
    "issues": [
      {
        "code": "BUTTONS_TOO_MANY",
        "path": "/messages/0/blocks/1/buttons",
        "message": "Max 5 buttons per button_group (got 8).",
        "severity": "error",
        "limit": 5,
        "actual": 8
      },
      {
        "code": "INSECURE_URL",
        "path": "/messages/0/blocks/2/url",
        "message": "URLs must use https:// (got http://).",
        "severity": "error"
      }
    ]
  }
}

path

string

A JSON Pointer into the cleaned-up payload. If you used shortcuts, the numbers may not match your raw body.

severity

string

error removes the block, warning changes it visibly, info is just a note.

limit

number

The cap, on limit issues.

actual

number

What you sent.

Every other failure uses the same wrapper, without issues:

{ "ok": false, "error": { "code": "conversation_taken_over", "message": "An operator has taken over this conversation." } }

Ignoring HTTP responses in Make or n8n? The same issues show in your bot’s delivery log, so you can still find out why nothing appeared.

Issue codes

Rejects the whole payload

Code	Meaning
`UNRECOGNIZED_ENVELOPE`	Not a shape we accept. The message lists every shape we take.
`BLOCK_KIT_VERSION_UNSUPPORTED`	`block_kit_version` was not `"1"`.
`PAYLOAD_TOO_LARGE`	Over 256 KB.
`TOO_MANY_MESSAGES`	Over 10 messages — usually a loop bug in a scenario.

Removes one block

Code	Meaning
`MISSING_REQUIRED_FIELD`	A needed field is missing, or the block failed its schema.
`INVALID_MESSAGE`	Not a message or block shape we recognize.
`FORM_EXCLUSIVITY`	More than one form, or a form next to a `button_group`.
`BUTTONS_TOO_MANY`	Over 5 in one `button_group`.
`INTERACTIVE_BLOCKS_TOO_MANY`	Over 5 interactive blocks, or over 5 cards.
`FORM_FIELDS_TOO_MANY`	Over 10 fields.
`OPTIONS_TOO_MANY`	Over 50 select options.
`DUPLICATE_ACTION_ID`	Two buttons share an `action_id` in one message.
`DUPLICATE_FIELD_NAME`	Two fields share a `name`, or two forms share a `form_id`.
`VALUE_TOO_LONG`	Button `value` over 2,000 characters.
`URL_TOO_LONG`	Over 2,048 characters.
`INSECURE_URL`	Not `https://`.
`FIELD_TOO_LONG`	A `mid` that breaks `^[a-zA-Z0-9_.:-]{1,64}$`.

Warnings — it still goes through

Code	Meaning
`BLOCKS_TRUNCATED`	Over 25 blocks. First 25 kept, plus a note.
`TEXT_TRUNCATED`	Over 12,000 characters. Cut, with a visible ending.
`METADATA_TOO_LARGE`	Over 2 KB. Metadata removed, blocks kept.
`UNKNOWN_BLOCK_TYPE`	A `type` we do not know. Placeholder in the app, skipped on public pages.
`suppressed_default_body`	You returned `Accepted`, `OK`, or similar.

Notes

Code	Meaning
`PROGRESS_CLAMPED`	A `statusprogress` outside 0–100 was pulled back in.
`unknown_fields_dropped`	Fields we do not know were removed.
`ack_no_message`	Empty body or `{}` — got it, nothing created.

HTTP status codes

Status	Codes
`400`	`MALFORMED_MULTIPART`, `AMBIGUOUS_UPDATE_TARGET`
`401`	`token_invalid`, `invalid_api_key`
`402`	`MESSAGE_CAP_REACHED`, `STORAGE_CAP_REACHED`
`403`	`not_bot_authored`, `wrong_chatbot`
`404`	`conversation_not_found`, `message_not_found`
`409`	`conversation_taken_over`
`410`	`RESPONSE_URL_EXPIRED`
`413`	`PAYLOAD_TOO_LARGE`, `FILE_TOO_LARGE`
`415`	`IMAGE_FORMAT_UNSUPPORTED`
`422`	`BLOCK_VALIDATION_FAILED`, `EMPTY_BODY`, `FRAMEWORK_DEFAULT_BODY`, `FILE_TYPE_BLOCKED`
`429`	`rate_limited`, `UPDATE_LIMIT_REACHED`
`500`	`PERSIST_FAILED`, `UPLOAD_FAILED`

A 429 includes retry_after in seconds. Wait that long instead of hammering.

Get started

Sending messages

Block Kit

Receiving events

No-code platforms

Limits

Two kinds of failure

The error body

Issue codes

Rejects the whole payload

Removes one block

Warnings — it still goes through

Notes

HTTP status codes

​Limits

​Two kinds of failure

​The error body

​Issue codes

​Rejects the whole payload

​Removes one block

​Warnings — it still goes through

​Notes

​HTTP status codes

Limits

Two kinds of failure

The error body

Issue codes

Rejects the whole payload

Removes one block

Warnings — it still goes through

Notes

HTTP status codes