Error Handling

This page covers errors from calling SendSms and Balance — the requests you send to the API. It doesn't cover delivery outcomes reported back to you; see Transaction Status for that.

All API responses include a Status field. If Status is "Failed", check the Message field for error details.

Common errors include authentication failure, missing fields, or invalid parameters.

Failures still return HTTP 200

The API returns HTTP 200 OK even when a request fails. Do not rely on the HTTP status code — always check the Status field in the response body, and treat "Failed" as an error.

Two kinds of failure

Handle these differently — retrying the wrong one wastes credit or hides a bug:

• Transport failures — the request never got a response at all: a network error, a timeout, or an HTTP 5xx from an intermediary. There's no Status to read here because you don't have a response body. These are usually safe to retry with backoff.
• API-level failures — you got a 200 OK back with Status: "Failed" in the body. The request was received and rejected. Retrying the exact same request will fail the same way, so fix the request (credentials, fields, format) before sending it again.

No idempotency key

There's no documented idempotency key for SendSms. If a transport failure leaves you unsure whether a message actually went out, retrying can send it twice. Prefer checking Transaction Status or your own send logs for the MsgFollowUpUniqueCode before resending, rather than retrying blind.

Known error messages

Message	Seen on	Likely cause
Wrong Username or Password.	SendSms, Balance	userdata.username or userdata.password doesn't match your Comms credentials.
walletType must either be Local or International	Balance	walletType was sent as null or an unrecognized value instead of being omitted. See walletType.

Message text is meant for humans, not machine parsing — treat it as a starting point for troubleshooting, not a stable error code to switch on in code.

Response Structure

All API responses are JSON objects. The fields returned depend on the method called.

Field	Type	Description
Status	string	"OK" if request succeeded, "Failed" otherwise
Message	string	Reason for the failure. Only present when Status is "Failed"
Cost	number	Cost of sent messages, not always a whole number (only when Status is "OK", for SendSms)
MsgFollowUpUniqueCode	string	Unique tracking code (only when Status is "OK", for SendSms)
Balance	integer	Current account balance (for Balance requests)

When Status Is "Failed"

Use this checklist to quickly isolate the cause:

Read Message: It usually contains the exact reason (e.g., auth failure, missing field).

Verify credentials: Confirm API username and API key match your Comms settings.

Validate request payload: Make sure method, userdata, and required fields are present.

Check numbers and sender ID: Use international format for numbers and keep sender ID ≤ 11 characters.

Confirm environment: If you are testing, switch to sandbox; for production, switch to live.

Retry with a minimal request: Send a single SMS with default settings to confirm the basics.

Capture the raw request/response: Log the outgoing JSON and the full response for support.

If the issue persists, contact support and include the full response and your request payload.

Next steps

• Sending SMS — request and response fields for SendSms.
• Balance Inquiry — request and response fields for Balance.
• Transaction Status — per-message delivery outcomes, reported separately from request errors.
• SDK & Model Reference — the ApiResponseCode enum and ApiResponse model.