engine_error — WhatsApp engine error
What the API returns
{
"error": {
"code": "engine_error",
"message": "The WhatsApp engine returned an error.",
"request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
}
}Every Wapito error is this one envelope. Branch on code, which is stable; message is written for people and can be reworded; details appears only when there is something specific to say; request_id is what to quote to support.
What it means
engine_error is an HTTP 502 error from the Wapito WhatsApp API: whatsApp engine error. The response message reads “The WhatsApp engine returned an error.” It is retryable: the same request can succeed later without changes. 4 endpoints can raise it, POST /groups among them.
Why it happens
The engine that holds the WhatsApp session answered the request with a failure Wapito could not map to a more specific code: WhatsApp rejected the action for that chat, the session hit a protocol error mid-call, or the engine returned a body that was not what its own contract promises. The response quotes what the engine said in details so the reason is not lost, and the request_id ties it to our logs. Some of these are transient and some are specific to one chat or one media file.
How to fix engine_error
Read the quoted engine message in details before retrying; a rejection tied to the target chat or media will repeat, while a session hiccup will not.
Retry once with backoff; if the same call keeps failing, check the channel's health and whether the number is still connected on the phone.
Report a repeatable 502 with its request_id and the quoted engine message, because an unmapped engine answer is usually a mapping we should add.
The same failure in other stacks
If you are moving from a library or a self-hosted gateway, this is the same failure under the name that stack gives it:
WAHA 500 Internal Server Error
Endpoints that raise it
Where you will meet it
- Create Group
Feature guide
Retry guidance
Safe to retry
The condition is transient, so the same request can succeed later without any change on your side. Retry with exponential backoff and jitter — start at one second, double each attempt, cap at a minute — and stop after a handful of tries so a stuck condition surfaces as an alert rather than a hot loop.
Frequently asked questions
Does a 502 mean the message went out?
It means the engine did not confirm it, which is not the same as no. For a send, check the message's status through the reference endpoint or wait for the messages.status webhook before resending, because a retry of a message that did go out is a duplicate the recipient will notice.
How is engine_error different from engine_unavailable?
With engine_unavailable the engine could not be reached at all, so nothing happened and a retry is safe. With engine_error the engine was reached and answered with a failure, so the action may have partly happened - a group created but its icon not set, for instance - and the quoted message in details is what tells you which.
Related
Try it on your own number
Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.