engine_timeout — Engine did not answer in time
What the API returns
{
"error": {
"code": "engine_timeout",
"message": "The WhatsApp engine did not respond in time.",
"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_timeout is an HTTP 504 error from the Wapito WhatsApp API: engine did not answer in time. The response message reads “The WhatsApp engine did not respond in time.” It is retryable: the same request can succeed later without changes. 4 endpoints can raise it, GET /channel/health among them.
Why it happens
The WhatsApp engine accepted the request but did not answer within the budget Wapito gives it, which happens when a large media file is still being processed, when WhatsApp's servers are slow to acknowledge a send, or when the session is reconnecting. The outcome is genuinely unknown: the action may have completed after the deadline. That is the important difference from a 503, where nothing happened at all, and it is why a send should be checked before it is repeated.
How to fix engine_timeout
For a send, look the message up or wait for the messages.status webhook before retrying, so a slow success is not turned into a duplicate.
For a read or an idempotent change, retry with backoff; the second call returns the current state whatever the first one did.
Keep uploads well under the size limits and prefer a stored media id over a remote URL, so the engine is not waiting on a download inside the request.
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
How long does Wapito wait before returning a 504?
A few seconds for ordinary calls and longer for media, tuned so that a normal WhatsApp round trip fits comfortably and a stuck one is reported rather than held open. The exact budget is not part of the contract, so build the retry logic on the status code and the message state rather than on a timer.
Why did the message arrive even though I got a 504?
Because the deadline passed on our side after WhatsApp had already accepted the message. The engine does not cancel work when the caller stops waiting, so the send completed and the delivery receipt followed. That is exactly why the fix steps say to check the message status before sending it again.
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.