Errors

Whats91 public API endpoints use one error envelope. Meta-compatible endpoints are the single exception: they return Meta-shaped error bodies so existing Cloud API clients keep working unchanged.

Error Envelope

Every non-Meta-compatible failure returns this body. success is always false, error_code is the stable machine-readable identifier to branch on, and message is human-readable text that may change.

{
  "success": false,
  "message": "Missing public API token",
  "error_code": "MISSING_AUTH_TOKEN",
  "details": {},
  "metadata": {
    "apiVersion": "v2",
    "requestId": "request-uuid"
  }
}

Response Headers

Authentication and Authorization

Request Shape

Rate Limiting

HTTP 429 means a Whats91 platform limit window was exhausted. It is produced before the request reaches a handler and carries no Meta error code. Back off, then resume. Meta throughput limits are reported separately as Meta error codes inside a successful HTTP exchange with the provider.

Meta-Compatible Endpoints

POST /api/v2/messages and POST /api/v2/{phoneNumberId}/messages return Meta-shaped errors rather than the Whats91 envelope, so a Cloud API client can be repointed at Whats91 without changing its error handling. The X-Whats91-Request-Id header is still present.

{
  "error": {
    "message": "Invalid parameter",
    "type": "OAuthException",
    "code": 100,
    "error_subcode": null,
    "fbtrace_id": "trace-id"
  }
}

Retry Guidance

• Never retry a 4xx other than 429 without changing the request; the same input produces the same result.
• Retry 429 and 5xx with exponential backoff and jitter.
• For sends, prefer idempotency-protected endpoints or a deduplication key in your own system: a retried send that already reached Meta creates a duplicate WhatsApp message.
• When a send returns an ambiguous provider outcome, read the message report before resending rather than sending again blindly.
• Treat a send response as an acceptance receipt, not a delivery receipt. Delivery, read, and failure arrive through webhooks and reports.