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"
}

Solution: Use the Webhooks to listen for device.disconnected events and prompt the user to reconnect via the dashboard.