Errors

CubeConnect uses standard HTTP status codes to indicate the success or failure of API requests.

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
202	Accepted	Message queued for delivery
400	Bad Request	Invalid request format
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
502	Bad Gateway	WhatsApp API unreachable
503	Service Unavailable	Service temporarily down

Response Format

All API responses use a unified envelope format.

Success

{
  "success": true,
  "data": {
    "status": "queued",
    "message_log_id": 4521,
    "conversation_category": "SERVICE",
    "cost": 0.0
  }
}

Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error description.",
    "details": {}
  }
}

The details field is only present for validation errors and contains field-level messages.

Error Codes

Authentication

Code	HTTP	Description
AUTHENTICATION_REQUIRED	401	Missing API key
INVALID_API_KEY	401	Invalid API key
API_KEY_NO_TENANT	403	API key is not linked to any tenant
TENANT_NOT_FOUND	403	Specified tenant not found for this API key
FORBIDDEN	403	Insufficient permissions

Validation

Code	HTTP	Description
VALIDATION_ERROR	422	Invalid request data (includes field-level details)
INVALID_PHONE_NUMBER	422	Invalid phone number format

WhatsApp

Code	HTTP	Description
NO_ACTIVE_ACCOUNT	422	No connected WhatsApp account for this tenant
MISSING_ACCESS_TOKEN	422	WhatsApp account is missing its Meta access token
TEMPLATE_NOT_FOUND	404	WhatsApp template not found
MESSAGE_SEND_FAILED	500	Failed to send message via WhatsApp API

Billing

Code	HTTP	Description
RATE_LIMIT_EXCEEDED	429	API rate limit exceeded for your plan
PLAN_LIMIT_REACHED	429	You have reached your plan's messaging limit
SUBSCRIPTION_EXPIRED	429	Your subscription has expired

General

Code	HTTP	Description
NOT_FOUND	404	The requested resource was not found
TENANT_CONTEXT_MISSING	500	Tenant context is missing from the request
INTERNAL_ERROR	500	An internal server error occurred

Common Errors

Authentication Errors

// 401 - Missing API key
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "API key is required."
  }
}

// 401 - Invalid API key
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key."
  }
}

// 403 - API key has no tenant
{
  "success": false,
  "error": {
    "code": "API_KEY_NO_TENANT",
    "message": "API key is not linked to a tenant."
  }
}

// 403 - Tenant not found
{
  "success": false,
  "error": {
    "code": "TENANT_NOT_FOUND",
    "message": "Tenant not found for this API key."
  }
}

Message Errors

// 422 - No active WhatsApp account
{
  "success": false,
  "error": {
    "code": "NO_ACTIVE_ACCOUNT",
    "message": "No active WhatsApp account found."
  }
}

// 422 - Missing access token
{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "Meta access token is missing."
  }
}

// 422 - Validation error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "phone": ["The phone field is required."],
      "data.text": ["The data.text field is required when message type is text."]
    }
  }
}

Rate Limiting & Billing

// 429 - Rate limit exceeded
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for your current plan."
  }
}

// 429 - Plan limit reached
{
  "success": false,
  "error": {
    "code": "PLAN_LIMIT_REACHED",
    "message": "You have reached your plan limit."
  }
}

// 429 - Subscription expired
{
  "success": false,
  "error": {
    "code": "SUBSCRIPTION_EXPIRED",
    "message": "Your subscription has expired."
  }
}

WhatsApp API Errors

When the WhatsApp Cloud API returns an error, it is forwarded in the webhook status update:

{
  "statuses": [
    {
      "id": "wamid.xxx",
      "status": "failed",
      "errors": [
        {
          "code": 131047,
          "title": "Message failed to send because more than 24 hours have passed since the customer last replied."
        }
      ]
    }
  ]
}

Common WhatsApp error codes:

Code	Description
131047	24-hour messaging window expired
131048	Spam rate limit hit
131051	Unsupported message type
131026	Message undeliverable (blocked or invalid number)
130472	Number not registered on WhatsApp
132000	Template parameter count mismatch
132012	Template not found
132015	Template paused or disabled

Handling Errors

Best Practice

Always check the HTTP status code before processing the response body. Implement retry logic for 429 and 5xx errors, but do not retry 4xx errors without fixing the request.