Error Handling

All API errors return JSON with a consistent format.

Error Response Format

Every error response follows this structure:

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

Validation Error Format

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

{
  "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	When It Occurs
`UNAUTHORIZED`	401	Missing API key	No `Authorization: Bearer` header provided
`INVALID_API_KEY`	401	Invalid or revoked API key	The provided API key doesn't exist, was revoked, or has expired
`NO_SESSION`	403	API key not linked to a session	The API key exists but is not bound to any WhatsApp session
`NOT_FOUND`	404	Resource not found	The requested message doesn't exist or doesn't belong to your session
`SESSION_NOT_CONNECTED`	422	Session not connected	Your session is not in a `connected` state — connect it from the dashboard
`VALIDATION_ERROR`	422	Invalid request parameters	Missing or invalid fields in the request body
`RATE_LIMITED`	429	Too many requests	Rate limit exceeded — wait and retry
`SEND_FAILED`	502	Message delivery failed	WhatsApp service accepted the request but couldn't deliver the message
`SERVICE_UNAVAILABLE`	503	WhatsApp service unreachable	The WhatsApp backend service is down or unresponsive

Example Error Responses

Missing API Key (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is required. Pass it as a Bearer token.",
    "status": 401
  }
}

Invalid API Key (401)

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked.",
    "status": 401
  }
}

Session Not Connected (422)

{
  "error": {
    "code": "SESSION_NOT_CONNECTED",
    "message": "The session linked to this API key is not connected. Connect it from the dashboard first.",
    "status": 422
  }
}

Send Failed (502)

{
  "error": {
    "code": "SEND_FAILED",
    "message": "Failed to send message.",
    "status": 502
  }
}

Service Unavailable (503)

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "WhatsApp service is unavailable. Try again later.",
    "status": 503
  }
}

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