Envelope, errors, pages
One response format, failure codes, cursor pagination and the limits.
On this page
The response envelope #
A successful answer always puts the content into data — even when it is a single object. Lists get nextCursor and hasMore next to it. A failure arrives in the same envelope with an error field carrying a machine code and an explanation.
Every response carries Cache-Control: no-store: they contain someone's conversation.
{"data": { … }}
{"data": [ … ], "nextCursor": "2026-08-22T09:15:04.281Z", "hasMore": true}
{"error": {"code": "validation_error", "message": "content must not exceed 4096 characters"}}Failure codes #
| HTTP | code | When |
|---|---|---|
| 400 | validation_error | the body did not parse or a value does not fit |
| 401 | unauthorized | no key, revoked or belonging to someone else |
| 403 | insufficient_scope | the key has no scope for the method |
| 404 | not_found | no such conversation, or it belongs to another site |
| 409 | conversation_closed | the conversation is closed, the visitor will not see the reply |
| 409 | no_visitor | the conversation has no widget visitor |
| 413 | file_too_large | the file behind the link is over the limit |
| 429 | rate_limit_exceeded | rate limit exceeded, see Retry-After |
| 502 | file_fetch_failed | the file behind your link did not download |
| 503 | storage_unavailable | the database or Redis is unreachable, retry later |
Pages #
Pagination is cursor based, not page numbers: while the first page is being read visitors keep writing, and numbering would push some conversations past the reader. The cursor is the time of the last shown item in RFC 3339 with nanoseconds.
Take nextCursor from the answer and pass it as the cursor parameter while hasMore is true.
| Field | Type | Req. | Description |
|---|---|---|---|
| limit | int | no | page size: 25 by default, 100 at most |
| cursor | string | no | continuation: the nextCursor value of the previous answer |
Limits #
| What | How much |
|---|---|
| Requests per key | 300 per minute, then 429 with Retry-After |
| Page size | 25 by default, 100 at most |
| Reply length | 4096 characters |
| Request body | 256 KB |
| File behind a link | 50 MB |
| Signed attachment link lifetime | 1 hour |
| Waiting for your webhook handler | 20 seconds |
| Webhook delivery attempts | 3, a 5 second pause doubling after that |
| Webhook signature window | 5 minutes |