Errors
InboxIQ uses standard HTTP status codes and returns the same JSON shape for every error.
Error format
{ "timestamp": "2026-11-06T12:32:10.512Z", "status": 400, "error": [ "Invalid phone number" ], "path": "uri=/api/v1/send-sms", "message": "Invalid phone number"}| Field | Description |
|---|---|
status | The HTTP status code. |
error | A list of messages. Validation errors list every problem found in the request. |
message | A summary of the error you can log or show to your team. |
path | The endpoint that was called. |
timestamp | When the error happened, in UTC. |
reference | Only on unexpected server errors. Quote it when you contact support. |
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 Bad Request | The request is invalid: a required field is missing, a value is not valid or there is not enough credit. | Read the error list, fix the request and try again. |
| 401 Unauthorized | The Basic authentication credentials are missing or wrong. | Check the username and password you send. |
| 403 Forbidden | You are not allowed to see this resource, for example a batch from another account. | Check you are using the right account and reference. |
| 404 Not Found | The application key was not recognised, or the record does not exist. | Check the key header and any references you send. |
| 500 Internal Server Error | Something went wrong on InboxIQ’s side. | Retry after a short wait. If it continues, contact support with the reference from the response. |
Common messages
| Message | Cause and fix |
|---|---|
Invalid phone number | The destination is not an Econet, NetOne or Telecel mobile number. |
Phone number contains white spaces | Remove spaces from the destination. |
Message Text cannot be blank | messageText is missing or empty. |
Primary email recipients should be provided | toRecipients is missing or empty. |
Subject should be provided | The email subject is missing. |
Email body should be provided | The email body is missing. |
You do not have enough credit to send … | Top up SMS credits or upgrade your email package. |
Invalid api access key supplied | The key header is missing or does not match any of your applications. |
Retrying safely
- Do not retry
400,401,403or404errors without changing the request. They will fail again. - For
500errors and network timeouts, wait a few seconds and retry, increasing the wait each time. - A timeout does not always mean the message was not sent. Check SMS History before resending an important message.