Skip to main content
To simplify integration and error handling in your code, our API uses a standardized JSON response format across all endpoints. When an error occurs, the isSuccess flag is false, and the details of the error are elaborated inside the errors object.

​
Error Response Structure

{
  "isSuccess": false,
  "errors": {
    "code": "RATE_001",
    "group": "TOO_MANY_REQUESTS",
    "description": "Rate limit exceeded. Please try again later.",
    "params": {
      "limit_type": "sec",
      "retry_after": "1 seconds"
    }
  }
}
​
isSuccess
boolean
required
Always false in the event of an error.
​
errors.code
string
A specific, unique application error code (e.g., AUTH_001).
​
errors.group
string
Indicates the general category the error belongs to (e.g., UNAUTHORIZED, VALIDATION).
​
errors.description
string
A human-readable description of the error.
​
errors.params
object
(Optional) Contains dynamic data related to the error (e.g., how long to wait before retrying).

​
HTTP Status Codes

In addition to the specific application error codes, the API uses standard HTTP status codes:
  • 400 Bad Request: The request body is malformed or missing required fields.
  • 401 Unauthorized: Authentication failed (API Key is missing or invalid).
  • 402 Payment Required: Your billing account has insufficient balance.
  • 403 Forbidden: Authentication succeeded, but you do not have permission.
  • 429 Too Many Requests: You have hit the high-performance rate limits. Wait for the retry_after duration.
  • 500 Internal Server Error: An unexpected error occurred on the server side.
  • 502 Bad Gateway: An error occurred while communicating with upstream servers (Meta/WhatsApp).

​
Application Error Codes Dictionary

Below is a list of specific errors.code values that may be returned by the API. You can build your error handling (try-catch) mechanisms around these specific codes to build a robust integration.

​
Authentication & Security

Error CodeHTTP StatusError GroupDescription
AUTH_001401UNAUTHORIZEDAPI Key not found, invalid, or expired.
AUTH_002401UNAUTHORIZEDMissing Authorization header.
AUTH_003401UNAUTHORIZEDInvalid token format. It must be ‘Bearer <token>’.
AUTH_004500INTERNAL_ERRORAn error occurred in the authentication service.

​
WhatsApp Credentials (WABA)

Error CodeHTTP StatusError GroupDescription
WABA_001401UNAUTHORIZEDWABA credentials are missing or invalid.

​
Billing & Balance

Error CodeHTTP StatusError GroupDescription
BILL_001402PAYMENT_REQUIREDInsufficient balance. Please top up your account.
BILL_002400BAD_REQUESTNo billing account found associated with the API Key.

​
Rate Limiting

Error CodeHTTP StatusError GroupDescription
RATE_001429TOO_MANY_REQUESTSRate limit exceeded. Please try again later. (Dynamic wait time is returned in the params object)