Responses & Errors

When sending a request with an invalid msg part to the JSON gateway, it will continue to check the other to objects and msg objects available and send the correctly formatted values. In the JSON response, you can find details per message. With each message you receive the PhoneNumber of the failed message (if present), the accepted or rejected status, your reference for the message (if present), the amount of message parts we created for that message, and a description why the message was rejected (if present).

Acceptance by the gateway (aka receiving errors) is not the same as actual delivery of a message. Delivery is done asynchronously and as such you can only receive information about delivery status via the status report webhooks.

Examples of responses of failed JSON requests:

Entire request incorrect:

Status: 400 Bad Request

{
  "details": "No account found for the given authentication",
  "errorCode": 101,  //See table "JSON POST Error codes" below
  "messages": []
}

Incorrect msg and a correct message:

Status: 200 OK

{
  "details": "Created 1 message(s)",
  "errorCode": 201, //See table "JSON POST Error codes" below
  "messages": [
    {
      "to": "00447911123456",
      "status": "Accepted",
      "reference": "your_reference_A",
      "parts": 1,
      "messageDetails": null,
      "messageErrorCode": 0 //See table "JSON POST Error codes" below
    },
    {
      "to": "00447911123457",
      "status": "Rejected",
      "reference": "your_reference_B",
      "parts": 0,
      "messageDetails": "A body without content was found",
      "messageErrorCode": 304 //See table "JSON POST Error codes" below
    }
  ]
}

All incorrect:

Status: 400 Bad Request

{
  "details": "Created 0 message(s)",
  "errorCode": 201,
  "messages": [
    {
      "to": "0044791112345a",
      "status": "Rejected",
      "reference": "your_reference_A",
      "parts": 0,
      "messageDetails": "Gsm '0044791112345a' is not a number.",
      "messageErrorCode": 303 //See table "JSON POST Error codes" below
    },
    {
      "to": "00447911123456",
      "status": "Rejected",
      "reference": null,
      "parts": 0,
      "messageDetails": "A body without content was found",
      "messageErrorCode": 304 //See table "JSON POST Error codes" below
    }
  ]
}

NOTE: The XML gateway and JSON gateway have different output, and respond differently based on the error. For XML responses, please see the section on XML communication.

JSON POST responses

HTTP status	Error text	Remarks
405	(none)	No HTTP GET or POST was used to send your request
500	"details": "Unknown Error"	An unexpected error occurred. Check the provided values. Contact CM for support.
400	"details": "No account found for the given authentication"	No account found for the provided product token.
400	"details": "Insufficient balance."	Trial accounts only: You are out of trial messages. Order new messages via your dashboard. If you are a regular prepaid customer, you will be notified that you have run out of quota in a Status Report.
400	"details": "Message is unroutable."	Your request could not be routed. Contact CM for support.
400	"details": "Invalid product token."	Invalid or missing product token
400	"details": "A MESSAGES object requires at least one MSG object"	A MSG object within the MESSAGE object is required and is missing.
400	"details": "Invalid JSON"	The given JSON is malformed. Please validate your JSON syntax and try again.
200	"details": "Created [x] message(s)"	An [x] amount of messages have been accepted. See the messages objects for further details.
-	"messageDetails": "No FROM field found in a MSG object."	The ‘FROM’ element is missing within the ‘MSG’ element
-	"messageDetails": "Empty mobilenumber field, MT ignored"	The Phone Number value for the TO element is missing
-	"messageDetails": "Rejected: Gsm '[msisdn]' is not a number."	The value for the TO element is not a valid Phone Number
-	"messageDetails": "[Object] object is an invalid type, must be an array"	The stated [Object] should be an array. Even if this contains one element.
-	"messageDetails": "No body field was found"	The ‘BODY’ element is missing within the ‘MSG’ element
-	"messageDetails": "A body without content was found"	The ‘BODY’ element is missing ‘CONTENT’

JSON POST Error codes

Error code	Description
0	Ok
999	Unknown error, please contact CM support
101	Authentication of the request failed
102	The account using this authentication has insufficient balance
103	The product token is incorrect
201	This request has one or more errors in its messages. Some or all messages have not been sent. See MSGs for details
202	This request is malformed, please confirm the JSON and that the correct data types are used
203	The request's MSG array is incorrect
301	This MSG has an invalid From field (per msg)
302	This MSG has an invalid To field (per msg)
303	This MSG has an invalid Phone Number in the To field (per msg,)
304	This MSG has an invalid Body field (per msg)
305	This MSG has an invalid field. Please confirm with the documentation (per msg)
401	Message has been spam filtered
402	Message has been blacklisted
403	Message has been rejected
500	An internal error has occurred