Developer documentation

Build with the InboxIQ API

Reference

Errors

InboxIQ uses standard HTTP status codes and returns the same JSON shape for every error.

Error format

Error response
{
"timestamp": "2026-11-06T12:32:10.512Z",
"status": 400,
"error": [
"Invalid phone number"
],
"path": "uri=/api/v1/send-sms",
"message": "Invalid phone number"
}
FieldDescription
statusThe HTTP status code.
errorA list of messages. Validation errors list every problem found in the request.
messageA summary of the error you can log or show to your team.
pathThe endpoint that was called.
timestampWhen the error happened, in UTC.
referenceOnly on unexpected server errors. Quote it when you contact support.

Status codes

StatusMeaningWhat to do
400 Bad RequestThe 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 UnauthorizedThe Basic authentication credentials are missing or wrong.Check the username and password you send.
403 ForbiddenYou 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 FoundThe application key was not recognised, or the record does not exist.Check the key header and any references you send.
500 Internal Server ErrorSomething went wrong on InboxIQ’s side.Retry after a short wait. If it continues, contact support with the reference from the response.

Common messages

MessageCause and fix
Invalid phone numberThe destination is not an Econet, NetOne or Telecel mobile number.
Phone number contains white spacesRemove spaces from the destination.
Message Text cannot be blankmessageText is missing or empty.
Primary email recipients should be providedtoRecipients is missing or empty.
Subject should be providedThe email subject is missing.
Email body should be providedThe 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 suppliedThe key header is missing or does not match any of your applications.

Retrying safely

  • Do not retry 400, 401, 403 or 404 errors without changing the request. They will fail again.
  • For 500 errors 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.