Errors

Errors use standard HTTP status codes and a consistent JSON body:

{
  "error": {
    "code": "sender_id_not_approved",
    "message": "This sender ID is not approved for your account",
    "request_id": "req_7e099f34-ad34-475b-8549-76c26767059a"
  }
}

Use code in your code; message is for people and may change. Include request_id when you contact support.

Status codes

Status	Meaning
`400`	The request is invalid. Fix it before retrying.
`401`	The API key is missing or invalid.
`402`	Your balance is too low.
`403`	The key is not allowed to do this.
`404`	The resource does not exist on your account.
`409`	The request conflicts with an earlier one.
`429`	Too many requests. Wait and retry.
`5xx`	Something went wrong on our side. Retry with the same idempotency key.

Error codes

Code	Status	What to do
`validation_error`	400	A field is missing or invalid. `message` says which.
`invalid_recipient`	400	The number is not a valid Ghana mobile number.
`message_too_long`	400	Shorten the message to 480 characters or fewer.
`missing_text`	400	Give the batch or each recipient some text.
`no_valid_recipients`	400	None of the batch recipients were valid.
`invalid_api_key`	401	Check the key, or create a new one.
`insufficient_balance`	402	Top up your wallet.
`sender_id_not_approved`	403	Use an approved sender ID, or request one.
`ip_not_allowed`	403	Call from an allowed IP, or update the key's allowlist.
`account_suspended`	403	Contact support.
`not_found`	404	Check the ID.
`idempotency_conflict`	409	Use a new idempotency key for a different request.
`rate_limited`	429	Slow down. See Rate limits.
`otp_locked`	429	Too many wrong codes. Send a new code.
`otp_rate_limited`	429	Too many codes sent to this number. Try later.

Status codesCopy Anchor Link

Error codesCopy Anchor Link

On this page

Status codes

Error codes