Errors & rate limits
Errors use one JSON envelope with a stable machine-readable code. Each API key has a request budget, and a 429 tells you exactly how long to wait.
Error envelope
Non-2xx responses carry an HTTP status and a body with a stable machine-readable code, a human message, details and a request_id to quote to support. When the problem is a specific field, details.fields maps each field to what is wrong with it.
{
"error": {
"code": "validation_failed",
"message": "Enter the phone number with country code, e.g. +91 XXXXX XXXXX.",
"details": {
"fields": {
"to": "Enter the phone number with country code, e.g. +91 XXXXX XXXXX."
}
},
"request_id": "8c3f2a91b7d84e0f9a1c2b3d4e5f6a7b"
}
}When WhatsApp itself rejects a call, the error is meta_error and details carries Meta's own code:
{
"error": {
"code": "meta_error",
"message": "Template name does not exist in the translation",
"details": {
"meta_code": 132001,
"meta": { "title": "Template name does not exist in the translation", "message": "…", "details": "…", "subcode": null, "fbtrace_id": "A1b2C3…" }
},
"request_id": "1f0c…"
}
}Error codes
400), a missing Content-Type: application/json header (415), a body with a missing or wrongly typed field (422), an invalid UUID in the path (400) or a body over 25 MB (413) — are rejected before they reach Engage's handlers. They return a plain-text message instead of the JSON envelope. Unknown paths return an empty 404.Rate limits
Each API key gets a steady request rate, with short bursts of up to twice that rate allowed. When you go over, the API answers 429 rate_limited with a Retry-After header giving the whole seconds to wait.
Endpoint-specific limits
Message sending is additionally paced per WhatsApp number according to Meta's throughput tier. That pacing happens inside Engage's queue: you receive 202 immediately and messages are delivered as fast as WhatsApp allows.
Retrying safely
Retry 429, 500, 502 and network errors with exponential backoff and jitter. When sending messages, always send an Idempotency-Key so a retried request never sends twice.
async function engage(path, body, key = crypto.randomUUID()) {
for (let attempt = 0; attempt < 5; attempt++) {
const res = await fetch(`https://engage.swastik.ai/v1${path}`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ENGAGE_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": key, // same key on every retry
},
body: JSON.stringify(body),
});
if (res.ok) return res.json();
if (![429, 500, 502].includes(res.status)) {
const { error } = await res.json().catch(() => ({ error: { code: res.status, message: res.statusText } }));
throw new Error(`${error.code}: ${error.message}`);
}
const wait = Number(res.headers.get("Retry-After")) * 1000 || 2 ** attempt * 500;
await new Promise((r) => setTimeout(r, wait + Math.random() * 250));
}
throw new Error("Engage request failed after retries");
}