Docs

Errors & rate limits

Every error uses the same JSON envelope, and every response tells you how much rate-limit budget remains.

Error envelope

Non-2xx responses carry an HTTP status and a body with a stable machine-readable code, a human message, optional details and a request_id to quote to support.

422 Unprocessable Entity

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": {
      "to": "must be a valid phone number in E.164 format",
      "text.body": "must be at most 4096 characters"
    },
    "request_id": "8c3f2a91b7d84e0f9a1c2b3d4e5f6a7b"
  }
}

Error codes

Status	Code	Meaning	What to do
401	`unauthorized`	Missing, invalid, expired or revoked key	Check the Authorization header
401	`mfa_required`	Dashboard session needs a second factor	Dashboard only
402	`plan_limit`	A plan limit was reached (messages, contacts…)	Upgrade or wait for the next period
403	`forbidden`	Key lacks the permission or IP not allowed	Grant the permission
404	`not_found`	Resource doesn’t exist in this organization	Check the id
409	`conflict`	State conflict, or idempotency key reused with a different body	Re-read state; use a new key
422	`validation_failed`	Body failed validation; see details	Fix the fields listed in details
429	`rate_limited`	Too many requests	Wait for Retry-After seconds
502	`meta_error`	WhatsApp (Meta) rejected or failed the call	details include Meta’s code
500	`internal`	Unexpected server error	Retry with backoff

Rate limits

Each API key has a request budget per second based on your plan (Starter 20, Growth 100, Business 300 rps). Every response includes the standard headers:

Header	Description
`RateLimit-Limit`	Requests allowed in the current window
`RateLimit-Remaining`	Requests left in the current window
`RateLimit-Reset`	Seconds until the budget refills
`Retry-After`	On 429 only: seconds to wait before retrying

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. Always send an Idempotency-Key so a retried POST never creates a duplicate.

async function engage(path, body, key = crypto.randomUUID()) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(`https://api.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, 503].includes(res.status)) {
      const { error } = await res.json();
      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");
}