Skip to main content

​
Error Handling

WazzAPI uses standard HTTP status codes and a consistent JSON error format.

​
Error Format

All error responses share this structure: 
{
  "error": "ERROR_CODE",
  "message": "Human-readable description",
  "details": {
    "field": ["specific error information"]
  }
}

​
Common Error Codes

CodeStatusDescription
VALIDATION_ERROR400Invalid parameters. Check details for specific field errors.
UNAUTHORIZED401Missing or invalid API key.
NOT_FOUND404The requested resource (message, contact) does not exist.
RATE_LIMIT429Too many requests. Check Retry-After header.
QUOTA_EXCEEDED429Monthly message quota limit reached.
INTERNAL_ERROR500Something went wrong on WazzAPI’s side.

​
Handling Specific Errors

​
Validation Errors (400)

The details object will contain validation messages keyed by the invalid field name. 
{
  "error": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": {
    "phone": ["Must be in E.164 format (+123...)"],
    "message": ["Required"]
  }
}

​
Account Disconnected (400)

If the WhatsApp instance is disconnected (e.g., phone is offline or unlinked): 
{
  "error": "ACCOUNT_DISCONNECTED",
  "message": "WhatsApp account is not connected"
}
Solution: Use the Webhooks to listen for session.disconnected events and prompt the user to reconnect via the dashboard.