Skip to main content

API Error Reference

Complete reference for API error codes, response formats, and resolution steps.

Error Response Formats​

Standard Error Response​

[
  {
    "WarningMessages": ["Error description here"],
    "errorMsg": "Error description or null",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

HTTP 500 Server Error​

{
  "Message": "An error has occurred."
}

Null Response​

[
  null
]

Message Content Errors​

Invalid Recipients​

[
  {
    "WarningMessages": [],
    "errorMsg": "No recipients with valid addresses",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Causes:

  • Phone numbers not in international format
  • Invalid or malformed phone numbers
  • Empty recipients array
  • Non-existent phone numbers

Solutions:

  • Use international format: +447700900123
  • Validate phone numbers before sending
  • Remove invalid numbers from recipient list
  • Ensure at least one valid recipient

Message Too Long​

[
  {
    "WarningMessages": [
      "Message exceeds maximum length"
    ],
    "errorMsg": null,
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Keep SMS under 918 characters (6 parts max)
  • Split long messages into multiple sends
  • Use concatenated SMS for longer content

Invalid Message Content​

[
  {
    "WarningMessages": [
      "Message contains invalid characters"
    ],
    "errorMsg": null,
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Remove or escape special characters
  • Check for unsupported Unicode characters
  • Validate message encoding

Service Errors​

Server Error (HTTP 500)​

{
  "Message": "An error has occurred."
}

Solutions:

  • Retry request with exponential backoff
  • Check service status
  • Contact support if persistent

Rate Limiting​

[
  {
    "WarningMessages": [
      "Rate limit exceeded"
    ],
    "errorMsg": "Too many requests",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Implement client-side rate limiting
  • Add delays between requests
  • Use batch requests for multiple messages
  • Contact support for rate limit increases

Service Unavailable​

[
  {
    "WarningMessages": [
      "Service temporarily unavailable"
    ],
    "errorMsg": "Service unavailable",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Retry with exponential backoff
  • Check service status page
  • Implement circuit breaker pattern
  • Queue messages for later retry

Request Format Errors​

Malformed JSON​

HTTP 400 response with content parsing error.

Solutions:

  • Validate JSON syntax before sending
  • Check for trailing commas or invalid characters
  • Ensure proper Content-Type header

Missing Required Fields​

[
  {
    "WarningMessages": [
      "Required field 'message' is missing"
    ],
    "errorMsg": "Invalid request format",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Ensure all required fields are present
  • Check field names match API specification
  • Validate payload structure

Invalid Field Types​

[
  {
    "WarningMessages": [
      "Field 'recipients' must be an array"
    ],
    "errorMsg": "Invalid data type",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Check data types match API specification
  • Convert strings to arrays where required
  • Validate field formats

Callback URL Errors​

Invalid Callback URL​

[
  {
    "WarningMessages": [
      "Callback URL is not valid"
    ],
    "errorMsg": null,
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Ensure URL is properly formatted
  • Use HTTPS for callback URLs
  • Verify URL is accessible
  • Test callback endpoint separately

Callback Delivery Failed​

This doesn't cause message sending to fail, but callbacks may not be delivered.

Solutions:

  • Ensure callback endpoint is responding
  • Return 200 OK status from callback handler
  • Check for timeout issues
  • Implement retry mechanism for missed callbacks

Customer Account Errors​

Account Suspended​

[
  {
    "WarningMessages": [
      "Customer account is suspended"
    ],
    "errorMsg": "Account suspended",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Contact customer to resolve account issues
  • Check billing status
  • Verify account compliance

Insufficient Credit​

[
  {
    "WarningMessages": [
      "Insufficient credit to send message"
    ],
    "errorMsg": "Insufficient credit",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

  • Customer needs to top up account
  • Check billing arrangements
  • Contact finance team

Related Documentation: