Skip to content

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.

422 Unprocessable Entity
{
  "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:

502 Bad Gateway
{
  "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

StatusCodeMeaningWhat to do
401unauthorizedMissing, invalid, expired or revoked keyCheck the Authorization header
401mfa_requiredDashboard session needs a second factorDashboard only
402plan_limitAn account limit set by Engage was reached, the feature is turned off for your account, or the account is inactiveContact support
402insufficient_balanceYour wallet balance can’t cover this messageTop up in Settings → Billing; paused campaigns resume automatically
403forbiddenKey lacks the permission or IP not allowedGrant the permission
404not_foundResource doesn’t exist in this organizationCheck the id
409conflictDuplicate (e.g. a contact with that phone exists) or a request with the same Idempotency-Key is still runningRe-read state, or retry shortly
422validation_failedThe request is well-formed but not allowed — bad field, wrong state, closed window, opted-out contact, Idempotency-Key reused with a different bodyRead message and details.fields
429rate_limitedToo many requestsWait for Retry-After seconds
502meta_errorWhatsApp (Meta) rejected or failed the calldetails include Meta’s code
500internalUnexpected server errorRetry with backoff; quote request_id
Malformed requests
Requests that can't be parsed at all — invalid JSON (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.

AccountRequests per second, per key
Default100
Raised on requestCustom — contact support

Endpoint-specific limits

ActionLimit
Contact import10 per minute per organization
Contact export6 per minute per organization
Template sync from Meta6 per minute
Template submit30 per minute
Editing one template10 per minute
Webhook test send10 per minute per endpoint
Typing indicator6 per minute per conversation

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");
}
Something unclear or missing on this page? Tell us at contact@swastik.ai