Error Codes

When interacting with the SMSBAT API, you may encounter errors. We use conventional HTTP response codes to indicate the success or failure of an API request.

In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a message type is invalid, etc.).
• Codes in the 5xx range indicate an error with our servers.

HTTP Status Codes

Code	Status	Description
200	OK	The request was successful.
400	Bad Request	The request was unacceptable, often due to missing a required parameter or malformed JSON.
401	Unauthorized	No valid API key provided, or authentication failed.
403	Forbidden	The API key doesn’t have permissions to perform the request, or your account is suspended.
404	Not Found	The requested resource doesn’t exist.
415	Unsupported Media Type	The Content-Type header is missing or not set to application/json.
422	Unprocessable Entity	The request was formatted correctly but contained semantic errors (e.g., invalid phone number format).
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on SMSBAT’s end.

Error Response Format

When an API request results in an error, the response body contains a JSON object with more details about the problem.

{
  "status": 400,
  "error": "Bad Request",
  "message": "Missing required field: 'messages'",
  "code": 1001
}

Business Logic Error Codes (Internal Codes)

In addition to HTTP status codes, we may return a specific internal code to help you identify the exact reason for the failure.

Internal Code	Description	Suggested Action
1001	Invalid Request Format	Ensure your request body is valid JSON.
1002	Missing Required Field	Check the message property in the response to see which field is missing.
1003	Invalid Phone Number	Ensure the recipient number is in E.164 format (e.g., 380501234567).
1004	Unregistered Alpha Name	The from parameter contains an alpha name that has not been approved for your account.
1005	Insufficient Balance	Your account does not have enough funds to process the messaging campaign.
1006	Invalid Message Type	The type parameter must be one of the supported types (e.g., sms, viber_promo).
1007	Template Not Found	The requested Viber/OTP template ID is invalid or not approved.
1008	Invalid Carousel Items	A Viber Carousel must contain between 2 and 5 items.

[!TIP] If you encounter an error code not listed here, or if you believe an error was returned by mistake, please contact [email protected] and provide the exact response payload and headers.