Error handling v1.2

This pages describes a JSON response with an HTTP status in the range 400-999 as defined by the API. All endpoints will return error states conforming to this specification.

Please see request format for more information on making requests.

Error format

An erroneous response format will always contain the following attributes:

Attribute Type Description Methods
status
string Always "error" for a failed request. GET POST PUT DELETE
response
object Object describing the response. GET POST PUT DELETE
code
int The HTTP status code. GET POST PUT DELETE
subcode
int/null A unique number which can uniquely identify the cause of the error. Defaults to null if no additional information is available. GET POST PUT DELETE
message
string Text which describes the nature of the error. This should not be used to programatically examine the error case. GET POST PUT DELETE

GET, POST, PUT and DELETE response

{
    "status":      "error",
    "response":    {
        "code":         404,
        "subcode":      123,
        "message":      "This message will describe the error"
    }
}

The subcode may help identify the cause of the error in more detail, but can be null if no additional information is available.

HEAD response

HTTP/1.1 404 Not Found
Date: Thu, 25 Apr 2013 08:23:19 GMT
Server: Apache
Cache-Control: no-cache
Expires: Sat,  9 Sep 1989 11:00:00 GMT
X-SuT-Server: SUTAPI v0.0.1
Connection: close
Content-Type: application/json; charset=UTF-8

Special cases

In the case of some specific HTTP status codes, additional attributes may be present:

409 Conflict response

// GET, POST, PUT and DELETE only

{
    "status":      "error",
    "response":    {
        "code":         409,
        "subcode":      null,
        "message":      "This message will describe the error",
        "resource":     "message",
        "resource_id":	987654
    }
}

resource describes the type of conflicting resource, this may vary from the endpoint you made a request to. resource_id is an int/string which corresponds to the id of the resource. Use these values to avoid making additional GET requests. One or both attributes can be "null".

Error subcodes

In addition to the HTTP status code, we may provide a subcode which provides additional information about the error:

CodeSubcodeMessageDescriptionSpecific to
423
1
List $id is to be or has been targetedA campaign is scheduled to be sent to this list in the future or has been sent to this list in the last 72 hours.list
423
2
List $id is permanentThis list is permanent.list
423
3
List $id is attached to a formThis is the primary list for a form.list
423
4
Folder $id or one of its lists is to be or has been targetedA campaign is scheduled to be sent to a list in this folder in the future, or has been sent to a list in this folder in the last 72 hours.folder
423
5
Folder contains List $id which is permanentThis folder contains a permanent list.folder
400
6
Subscriber email is on the Do Not Contact list: $emailThe subscriber's email address has been found on the company/global Do Not Contact list.subscriber subscription
400
7
Subscriber email domain is on the Do Not Contact list: $emailThe subscriber's email address domain has been found on the company Do Not Contact list.subscriber subscription
400
8
Subscriber email is on the watch list: $emailThe subscriber's email address prefix or domain has been found on the Global Watch List.subscriber subscription
400
9
Subscriber MSISDN is on the Do Not Contact list: $msisdnThe subscriber's MSISDN has been found on the company/global Do Not Contact list.subscriber subscription
423
10
Message $id is lockedThis message is scheduled to be sent or has been sent.emailMessage smsMessage
400
11
(Dynamic content syntax error)A dynamic content syntax error - please see documentation for more info.emailMessage
409
12
Automation Rule $id cannot be unpaused: Dependent $resource resource $resource_id no longer existsIf an automation rule dependent resource (usually actiontarget, but for smsAutomation it could be list_id, email_list_id or message_id) is deleted, and the associated rule is paused, this error will be given if the user then tries to unpause the rule without changing the dependent resource.clickAutomation dateAutomation openAutomation smsAutomation subscriptionAutomation
409
13
Subscriber attribute 'email|msisdn' cannot be modified to the value '$email|$msisdn'. Please POST as a new subscriber.If a user makes a PUT request where email or msisdn is set to a value that matches another subscriber's data, but the existing subscriber is not accessible by the user, this error will be returned. In this instance, it will be necessary for the user to POST a new subscriber with the requested email or msisdn.subscriber