Always check ok first. Only then read result (on success) or description + error_code (on failure).
Overview
All methods return the same envelope, so you can write one parser and reuse it everywhere.
// success
{ "ok": true, "result": { ... } }
// failure
{ "ok": false, "description": "Human-readable error", "error_code": 401 }
Error codes
Code | Meaning | Typical cause & action |
400 | Bad request | Missing field or message does not exist — fix parameters. |
401 | Unauthorized | Token invalid or revoked — check the token. |
403 | Forbidden | Insufficient permission or message ownership. |
409 | Conflict | getUpdates called while a webhook is enabled. |
429 | Rate limited | Over 30 req/s — back off and retry. |
500 | Server error | Check the retry strategy below. |
50001 | MP business error | Rejected by business logic — read |
501 | Not implemented | Method not currently supported (see the method matrix). |
With valid authentication, an unknown API method returns JSON 404. Using an unsupported HTTP verb on a known endpoint returns JSON 405. Authentication and rate limiting can return 401 or 429 first.
Handling a 409
Call getWebhookInfo to confirm the webhook configuration. Do not run deleteWebhook yourself — it is a high-risk controlled operation. Contact the maintainer to resolve the conflict.
Error-handling example
async function readBotResponse(res) {
const data = await res.json().catch(() => null);
if (!res.ok || data?.ok !== true) {
const error = new Error("MPChat Bot API request failed");
error.httpStatus = res.status;
error.apiCode = data?.error_code;
throw error;
}
return data.result;
}
Retry strategy
For
429, slow down and retry with capped exponential backoff. Honor a retry delay if the response provides one.After a timeout, connection loss, or
5xx, a send request may already have succeeded. Before replaying a write, reconcile the outcome using your own operation records. RepeatingsendMessagecan create a second message.For
400,401, and403, correct the request, credentials, or permissions before retrying.For
409, check the active delivery mode in the linked polling and webhook guide.
Related
Never log full tokens or sensitive fields in error reports. See the production checklist for redaction rules.