Responses & errors

Two envelope styles, one for the frozen v1/v2 SMS API, one for the newer /api/v1 platform API, each completely consistent within itself.

v1 / v2 envelope

Every /v1/ and /v2/ response carries a boolean status, a stable responseCode string, and a human-readable message. Endpoint-specific fields (balance figures, message IDs, costs) sit alongside them.

json

{
  "status": true,
  "responseCode": "0200",
  "message": "Accepted",
  "messageId": "3c51beb1-a674-41d0-9e45-f5581418fb56"
}

Response codes

Field	Type	Required	Description
0200	success	No	Request accepted. For sends, the message is queued for dispatch.
0201	created	No	The resource was created. E.g. a contact added to a group.
0401	auth	No	Missing or invalid token. Check the Authorization header.
0402	billing	No	Insufficient SMS balance to cover the send. Top up and retry.
0403	permission	No	Your token is valid but lacks the scope for this endpoint. Recreate it with the right scopes.
0404	not found	No	The referenced resource doesn't exist. E.g. an unknown sender ID or group.
0409	duplicate	No	Duplicate send blocked: same sender + message + recipient already delivered today. Intentional. See below.
0422	validation	No	The request body failed validation. A missing field, a malformed phone number, an over-long message. The message field says which.

About 0409 duplicate protection

The platform refuses to send the identical message to the same number twice in one day under the same sender. It protects you from retry loops double-billing your customers. Senders flagged allow_duplicates (e.g. OTP senders where repeats are legitimate) bypass the check.

/api/v1 envelope

Platform resources (WhatsApp and other newer APIs) use a JSON envelope with conventional HTTP status codes:

Success: 200

{
  "success": true,
  "data": { "uuid": "…", "…": "…" }
}

Error: 4xx/5xx

{
  "success": false,
  "error": "validation failed: recipients are required"
}

HTTP status usage

Field	Type	Required	Description
200	OK	No	The request succeeded; the payload is under data.
400 / 422	client error	No	Malformed JSON or failed validation. The error string explains what to fix.
401	auth	No	No valid token. Same causes as v1's 0401.
403	forbidden	No	Valid token, insufficient scope/permission for this endpoint.
404	not found	No	Unknown resource UUID, or a UUID that belongs to another team.
409	conflict	No	The action clashes with current state (e.g. approving something already approved).
429	rate limited	No	Too many requests. Back off and retry with jitter.
500	server error	No	Something failed on our side. Safe to retry idempotent calls.

Retry guidance

Never blind-retry sends. A timeout doesn't mean the message failed. It may already be queued. Use v2 with your own trackingId so retries are traceable, or check delivery reports first.
Retry 429 and 5xx with exponential backoff starting at one second.
Do not retry 0422/400: the request itself is wrong and will fail identically.