Error Handling

WazzAPI uses standard HTTP status codes, but the exact JSON body can vary depending on the type of failure.

Error Format

Validation errors usually use a detail array format:

{
  "detail": [
    {
      "loc": ["body", "phone_number"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Application-rule failures usually return a simpler payload:

{
  "detail": "Message limit exceeded for your plan."
}

Code	Status	Description
`422 Unprocessable Entity`	422	Request validation failed before the request could be processed.
`401 Unauthorized`	401	Missing or invalid API key.
`404 Not Found`	404	The requested message, contact, template, or group does not exist.
`409 Conflict`	409	A duplicate resource already exists, such as a contact with the same phone number.
`429 Too Many Requests`	429	Request throttling or plan-based feature usage limit exceeded.
`500 Internal Server Error`	500	Unexpected server-side failure.

Field-level details are returned when the request body or query parameters are invalid.

{
  "detail": [
    {
      "loc": ["body", "whatsapp_account_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

If the WhatsApp account is disconnected or unavailable:

{
  "detail": "WhatsApp account is not connected"
}

What to do: Reconnect the device in Devices, or listen for device.disconnected on your webhook and reconnect before sending again.

You cannot change proxy settings while the device is still connected:

{
  "detail": "Disconnect this account before changing proxy settings."
}

What to do: Disconnect the device, update the proxy, then reconnect. See Proxy Support.

{
  "detail": "Only HTTP and SOCKS5 proxies are supported."
}

What to do: Use http://host:port or socks5://user:pass@host:port. HTTP proxies need an explicit port.