Errors and retries

Errors are always JSON and always carry an error field. Some also carry a code, which is the field to branch on, the human-readable text is written for a person reading a log and can change.

The two shapes of error

error is a string on every failure except schema validation, where it is a Zod object. A client that assumes one shape prints [object Object] into its logs at exactly the moment it most needs the detail.

1. A string

Everything except schema validation:

{ "error": "Phone number not found or not configured" }

2. A Zod object

Schema validation failures, on any endpoint with a request schema. formErrors holds problems with the body as a whole; fieldErrors maps a field name to an array of messages:

{
  "error": {
    "formErrors": [],
    "fieldErrors": {
      "to": ["String must contain at least 5 character(s)"],
      "event": ["Required"]
    }
  }
}

Flatten both shapes into one line before logging:

const message =
  typeof body.error === "string"
    ? body.error
    : [
        ...(body.error?.formErrors ?? []),
        ...Object.entries(body.error?.fieldErrors ?? {}).map(
          ([field, errs]) => `${field}: ${errs.join(", ")}`
        ),
      ].join("; ");

console.error(`[${res.status} ${body.code ?? ""}] ${message}`);

Status and code reference

Telling the two 429s apart

These are unrelated controls with opposite handling, and they share a status code. The distinguishing feature is whether limit, usage and limits are present in the body.

Key rate limit, retry

The per-key budget, 120 requests a minute by default. It clears inside the 60-second window, so a short back-off fixes it. The body carries error and nothing else:

{ "error": "Rate limit exceeded for this API key. Slow down or raise the key's limit." }

Account sending cap, do not retry

A per-minute, daily or monthly cap an administrator set, or an account with sending paused. It resets on its own cycle, not on a timer you control:

{
  "error": "daily sending limit reached (5000/5000). Ask your administrator to raise it.",
  "limit": "daily",
  "usage": { "minute": 12, "day": 5000, "month": 41233 },
  "limits": { "perMinute": null, "daily": 5000, "monthly": null, "paused": false }
}

Branch on the presence of those fields, not on the message text:

if (res.status === 429) {
  const capped = body.limit !== undefined;
  if (capped) {
"/docs/api/events"
    alertOperations(body.error);
    return "stop";
  }
"/docs/api/notifications"
  await sleep(Number(res.headers.get("RateLimit-Reset") ?? 5) * 1000);
  return "retry";
}

Only perMinute clears by waiting. A daily or monthly cap, and a paused account, need an administrator.

Retry policy

Suggested schedule: 1 s, 2 s, 4 s, 8 s, 16 s with jitter, maximum 5 attempts.

A failed send costs nothing

The charge for a message is a reservation taken before the handler runs. It is reversed automatically when the response status is 400 or above, any validation error, a closed window, a missing template, a Meta rejection, and when the client disconnects before the response is written.

So you never need to reconcile a failed send. The ledger keeps both movements, a DEDUCT and a matching REFUND, rather than deleting the row.

402 in both billing modes

The error sentence differs between credit-billed and wallet-billed plans. Match on reason, never on the text.

{
  "error": "Insufficient message credits, a marketing message costs 8 credits. Ask your administrator to add more.",
  "reason": "INSUFFICIENT_CREDITS",
  "category": "MARKETING",
  "creditsRequired": 8,
  "price": "0.0099",
  "currency": "USD",
  "balance": 3
}

{
  "error": "Insufficient wallet balance. Top up to continue sending.",
  "reason": "INSUFFICIENT_BALANCE",
  "category": "MARKETING",
  "creditsRequired": 8,
  "price": "0.0099",
  "currency": "USD",
  "balance": "0.0031"
}

The failures worth recognising on sight

409 TEMPLATE_NOT_APPROVED

The first thing a new account hits. Nothing sends until Meta approves your templates. Submit the catalog, then poll readiness, do not retry the send.

502 with (#133010)

The number was never registered on the Cloud API. Every send fails, with approved templates and credits in hand. Register it with a 6-digit two-step PIN under Phone Numbers → Register.

502 with (#132000)

Parameter count mismatch: the component array you sent does not match the approved template body. Only reachable on /v1/messages/send, the notifications API builds the array for you.

403 window closed

You sent a non-template message to someone who has not messaged you in 24 hours. Send it as an approved template.

200 with missingVariables

Not an error status, but treat it as one. The message was delivered with a literal - where a value should have been, and the credit was spent.

A client that handles all of it

async function send(payload, attempt = 0) {
  const res = await fetch("https://whatsapp-api.growcord.in/api/v1/notifications/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  const body = await res.json();

  if (res.ok) {
"https://whatsapp-api.growcord.in/api/v1/notifications/send"
    if (body.missingVariables?.length) {
      console.error("Sent with blank fields:", body.missingVariables);
    }
    return body;
  }

  const retryable =
    res.status >= 500 || (res.status === 429 && body.limit === undefined);

  if (retryable && attempt < 4) {
    const wait =
      res.status === 429
        ? Number(res.headers.get("RateLimit-Reset") ?? 5) * 1000
        : 2 ** attempt * 1000 + Math.random() * 500;
    await new Promise((r) => setTimeout(r, wait));
    return send(payload, attempt + 1);
  }

  const message =
    typeof body.error === "string"
      ? body.error
      : Object.entries(body.error?.fieldErrors ?? {})
          .map(([field, errs]) => `${field}: ${errs.join(", ")}`)
          .join("; ");

  throw new Error(`[${res.status} ${body.code ?? ""}] ${message}`);
}

Wrap that in a per-(event, order) deduplication check and it covers every failure mode in the table above.