Look up an error from an incoming webhook, the bot HTTP API or the event stream to see what it means and what to change.
Most errors are JSON with "ok": false:
"message" : " Bot is not a member of this chat "
Use error in your code. message explains the problem for people.
These responses aren’t JSON:
Status Body Cause 404 404 page not found (plain text)The URL doesn’t match any endpoint, for example a webhook URL with a missing token or an extra / at the end. 405 Empty, with an Allow header Wrong HTTP method. The chat list, attachment downloads and the event stream use GET; every other endpoint uses POST. 503 server is not ready (plain text)DonutChat is restarting or in maintenance. Retry with backoff. 400 or 426 Plain text A request to the event stream URL with a valid token but no WebSocket handshake.
errorReturned by Cause and fix invalid_jsonWebhook, Messages, Thread replies, Reply updates, Typing The body isn’t valid JSON, or a field has the wrong type. Send IDs as JSON numbers, not strings. missing_contentWebhook, Messages content is missing or empty.content_too_longWebhook, Messages, Thread replies, Reply updates content or content_chunk is over 80,000 UTF-8 bytes. Shorten the text or split it.missing_chat_idMessages, Thread replies, Reply updates, Typing chat_id is missing or isn’t a positive number.missing_parent_message_idThread replies, Reply updates parent_message_id is missing or isn’t a positive number.missing_reply_idReply updates reply_id is missing or isn’t a positive number.invalid_statusThread replies, Reply updates Create a reply with GN or OK; FL is only for updates, which accept GN, OK or FL. Mixed case such as Ok is rejected. invalid_content_typeMessages, Thread replies content_type must be TX or MD.invalid_avatar_urlMessages, Thread replies avatar_url must be an absolute http:// or https:// URL with no spaces around it.status_text_too_longTyping status_text is over 80 bytes. The message says characters, but the limit counts bytes.invalid_activityActivity An unknown field, an invalid value, a non-positive ID or sequence, extra data after the JSON, or a body over 4,096 bytes. invalid_idAttachments An ID in the path isn’t a positive 64-bit integer. invalid_multipart, missing_payload, missing_file, empty_file, too_many_filesThread replies with files Send one payload part and one to four non-empty file parts. See Attach files .
Every endpoint returns unauthorized. The message tells you which check failed:
messageCause and fix Missing or invalid Authorization header. Use: Authorization: Bearer <token>No token, or the header isn’t exactly Bearer, a space and the token. On the event stream, you can pass ?token= instead. Invalid bot tokenThe token is wrong or was regenerated, or the bot is paused. Use the current token, or switch the bot back on . Bot bearer token requiredAn attachment download was sent without a token. Invalid webhook tokenThe webhook URL is wrong, its token was rotated, or the webhook was deleted. Use the URL exactly as copied from the app.
errorReturned by Cause and fix not_in_chatMessages, Thread replies, Reply updates, Typing, Activity The bot isn’t an active member of the chat: it was never added or was removed, or the chat was deleted. Add the bot to the chat . not_ownerReply updates No reply from this bot matches the reply_id, chat_id and parent_message_id. The reply may not exist, may be deleted or may belong to another bot. Use the IDs of the reply you created. activity_unavailableActivity The IDs don’t identify a reply from this bot, or the step can’t change that way, for example retrying without an earlier failed. attachment_unavailableAttachments The bot isn’t an active member of the chat. webhook_disabledWebhook The webhook is switched off. Switch it on in the app. uploads_disabledThread replies with files The bot’s owner hasn’t turned on Allow file uploads execution_requiredMessages, Thread replies, Reply updates, Activity Posting by this bot is paused in this chat. This is rare. Don’t retry in a loop.
errorReturned by Cause and fix not_foundWebhook The webhook ID in the URL isn’t a number. Use the URL exactly as copied from the app. attachment_unavailableAttachments The file, message or reply doesn’t exist, was deleted or has expired, or the IDs don’t belong together. For a file in a top-level message, also when the bot was never added to the chat or was removed.
errorReturned by Cause and fix attachment_unavailableAttachments The file is larger than 10 MiB, the most a bot can download. file_too_large, payload_too_large, request_too_largeThread replies with files A file is over 10 MiB, or the request is too large.
errorReturned by Cause and fix unsupported_file_typeThread replies with files A file’s contents aren’t PNG, JPEG, GIF, WebP, PDF or UTF-8 text. Renaming a file or declaring another type doesn’t change this.
errorReturned by Cause and fix rate_limit_exceededWebhook More than 60 requests in the past minute or 1,000 in the past hour for this webhook. Requests rejected for bad JSON or content count too. There’s no Retry-After header: wait, then retry with backoff. busyAttachments Too many downloads at the moment. Retry later with backoff. rate_limitedThread replies with files The bot uploaded 30 files in the past hour. Wait, then retry. uploads_busyThread replies with files Too many uploads at the moment. Retry with backoff.
errorReturned by Cause and fix send_failedWebhook, Messages The sender name is over 32 bytes: username, or the bot’s name when you don’t send username. Otherwise a server error. create_failedThread replies The parent message doesn’t exist, was deleted, is in another chat or is itself a thread reply, or username is over 64 bytes. Otherwise a server error. stream_failedReply updates Overlapping updates to the same reply, or a server error. Send one update at a time per reply, then retry. membership_check_failedThread replies, Reply updates, Activity A temporary problem. Retry. list_failedChats A temporary problem. Retry. typing_failedTyping The typing indicator wasn’t sent. Retry or skip it. upload_failedThread replies with files The files couldn’t be stored, and nothing was kept. Retry. internal_errorEvent stream The connection couldn’t start. Reconnect with backoff.
errorReturned by Cause and fix threads_unavailable, typing_unavailable, activity_unavailable, unavailable, stream_unavailable, uploads_unavailableThread replies, Typing, Activity, Attachments, Event stream The feature is temporarily unavailable. Retry with backoff.
Once the connection is open, the event stream never sends error messages. It ends in one of these ways:
How it ends Cause What to do Close code 1000, reason server shutdown Another connection for the same bot replaced this one, or DonutChat is restarting. Run one copy of your integration, and reconnect with backoff. No close frame (code 1006 or end of stream) Your client sent nothing for 5 minutes, didn’t answer a ping within 10 seconds or read events too slowly, or the network failed. Send a short text frame every minute or two, and reconnect with backoff and last_event_id.
For 400, 401, 403, 404 and 413, fix the request. Sending it again unchanged fails again.
For 429, 500 and 503, retry with exponential backoff, after checking the causes listed above.
Creating a message or reply isn’t idempotent: if a create request times out without a response, it may already have posted, and retrying can post it twice. Retrying a reply update with the full text is safe.