Jump to section

Error Handling

All API errors return JSON with a consistent format.

Error Response Format

Every error response follows this structure:

Validation Error Format

When request validation fails (422), the response includes field-level errors:

General Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the error.",
    "status": 422
  }
}

Validation Fields

{
  "message": "The to field is required. (and 1 more error)",
  "errors": {
    "to": ["The to field is required."],
    "message": ["The message field is required."]
  }
}

Error Codes Reference

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing API key or no header provided
`INVALID_API_KEY`	401	Invalid, revoked, or expired API key
`NO_SESSION`	403	API key not linked to a WhatsApp session
`NOT_FOUND`	404	Resource not found belonging to you
`SESSION_NOT_CONNECTED`	422	Session not connected
`VALIDATION_ERROR`	422	Invalid request parameters body
`RATE_LIMITED`	429	Rate limit exceeded
`SEND_FAILED`	502	Message delivery failed (WhatsApp issue)
`SERVICE_UNAVAILABLE`	503	WhatsApp underlying service unreachable

Handling Errors in Code

const response = await fetch('/api/v1/messages/text', { ... });
const data = await response.json();

if (!response.ok) {
  console.error(`Error ${data.error.code}: ${data.error.message}`);
  // Handle specific error codes
  if (data.error.code === 'SESSION_NOT_CONNECTED') {
    // Prompt user to connect their session
  }
}