Errors
Errors are returned as JSON with an error string and the appropriate HTTP status. Bodies are stable — safe to match on.
Authentication errors (401 / 403)
| Status | Body | Meaning |
|---|---|---|
| 401 | {"error":"Missing site key"} | You didn't send X-Envara-Site-Key. |
| 401 | {"error":"Invalid site key"} | Key doesn't match any site. Check for stray spaces or wrong env. |
| 401 | {"error":"Invalid signature"} | HMAC mismatch. You likely signed a different body than you sent (e.g. middleware reformatted JSON). |
| 401 | {"error":"Stale timestamp"} | Clock drift > 5 minutes. Sync NTP on your server. |
| 403 | {"error":"Site is disabled"} | Re-enable the site from the dashboard. |
Server errors (5xx)
| Status | Body | Meaning |
|---|---|---|
| 500 | {"error":"<message>"} | Unexpected — retry with exponential backoff. If it persists, contact support with your event_id. |
Successful responses with no send
An event can be accepted (200 OK) without any WhatsApp message going out. Check the whatsapp field:
no_bindings— no binding configured for this site+event. Create one in the dashboard.skipped_no_phone— no recipient phone could be resolved (missingcustomer.phone_e164and no static recipient).skipped_no_config— WhatsApp Cloud credentials missing in Settings.
Per-recipient failures
If some recipients succeed and others fail, the response returns "whatsapp": "partial" with recipients_sent and recipients_failed counts. Per-message error details (Meta error code, reason) are visible in the Notification Log.
Retries & idempotency
If your request fails with a 5xx or network error, retry — but include X-Envara-Idempotency-Key with a stable per-event value to make sure duplicates are deduplicated server-side.