engine_unavailable — Engine unreachable
What the API returns
{
"error": {
"code": "engine_unavailable",
"message": "The WhatsApp engine is unavailable.",
"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_unavailable is an HTTP 503 error from the Wapito WhatsApp API: engine unreachable. The response message reads “The WhatsApp engine is unavailable.” It is retryable: the same request can succeed later without changes. 3 endpoints can raise it, GET /channel/health among them.
Why it happens
Wapito could not reach the WhatsApp engine process that holds this channel's session: the engine is restarting, its container is being replaced during a deploy, the connection was refused, or the deployment does not run the engine the channel asks for. The request never reached WhatsApp, so nothing was sent or changed. This is the status to expect for a minute or two around maintenance and the one a health check should tolerate briefly before paging anyone.
How to fix engine_unavailable
Retry with exponential backoff starting at a couple of seconds; the engine normally comes back within a minute and the request is safe to repeat.
Poll the channel health endpoint while backing off, so your worker resumes the moment the engine answers rather than on a fixed timer.
If the 503 lasts more than a few minutes, check the status page and open a ticket with the request_id; a stuck engine is on us to restart.
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:
ECONNREFUSED
Endpoints that raise it
Where you will meet it
- Connect a Number
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
Is the channel disconnected when I see this?
Not necessarily. The engine holds the session, and while the engine is down nobody can tell whether the phone is still linked. Once the engine is back the channel's status in the dashboard and the channel webhook event report the real state; treat the 503 as unknown rather than as disconnected.
Will queued webhooks be lost while the engine is unavailable?
No. Deliveries to your receiver are queued on Wapito's side with retries, and inbound events that the engine buffered are processed when it reconnects. What you may see afterwards is a short burst of events with timestamps from the outage window, so key your handlers on the event id rather than on arrival order.
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.