Errors

Error characteristics

All methods

If an error is returned then the associated code will be from the set identified in the 'Error List' section. If the error return is from the class of errors ARG_<DETAIL> then the argumentIndex will indicate which argument is in error. If the error return is from the class of errors ATTRIBUTE_<DETAIL> then both the argumentIndex and the attributeName will be set to indicate which attribute on the supplied argument is in error. Each error may optionally include context to provide any additional context to aid in understanding the error.

To the extent possible the implementation will attempt to validate all arguments and the associated attributes and return a set of errors as opposed to returning a single error reflecting the first error encountered.

In general clients should rely on the associated code from the Error/Warning and create their own text to relay to their customers in their language of choice. These codes will remain constant over time and come from the finite set defined in the Error/Warning section. The message provided with the Error/Warning is for convenience/development only. No assumption should be made about the stability over time of the text in the message attribute of the Error. This text may be localized and will commonly change as the API is upgraded.

The standard errors listed below may be generated by any of the methods, specific methods will generate additional errors. The definitive set of errors returned from a particular method is covered in the associated 'Errors returned' section.

• AUTHENTICATION_FAILURE – Authentication failure
• INTERNAL_ERROR – Internal error
• NO_SESSION – No current session

Create methods

Usually return at least:

• ARG_INVALID_TYPE – context object is of an incorrect type
• ARG_TOO_LARGE (for bulk creators) – maximum limit exceeded
• OBJECT_ EXISTS – attempt to create a duplicate object
• OBJECT_NOT_EXISTS – context in which new object is being created does not exist
• SYSTEM_LIMIT_EXCEEDED – the containing object has reached the maximum number of children

Delete methods

Usually return at least:

• ARG_NULL – driving object is null
• ARG_TOO_LARGE (for bulk deletors) – maximum limit exceeded
• OBJECT_NOT_EXISTS – object being referenced does not exist

Show methods

Usually return at least:

• ARG_NULL – driving object is null
• OBJECT_NOT_EXISTS – object being referenced does not exist

List methods

Usually return at least:

• ARG_NULL – driving object is null
• OBJECT_NOT_EXISTS – object being referenced does not exist
• RESULT_TOO_LARGE – maximum limit exceeded

Change methods

Usually return at least:

• ARG_NULL – driving object is null
• OBJECT_NOT_EXISTS – object being referenced does not exist

Add methods

Usually return at least:

• ARG_NULL – driving object is null
• ARG_TOO_LARGE (for bulk adders) – maximum limit exceeded
• OBJECT_NOT_EXISTS – object being referenced does not exist

Timeouts and Internal Errors

With the exception of a timeout or an INTERNAL_ERROR all errors should be considered final. Clients of the API may choose to re-invoke a method in error once, ideally after a reasonable back off period (for instance, 30 seconds).

The exception to this rule is the createSubCampaign method.

If the createSubCampaign method times out, clients should determine the state of the SubCampaign using the showSubCampaignState method and reference the SubCampaign using the externalId and Campaign fields. If this method returns an 'OBJECT_NOT_EXISTS' error then it is safe to retry, if this method returns successfully then it is safe to assume that the original method invocation succeeded and the SubCampaign will proceed as expected.

If the createSubCampaign method returns an internal error (INTERNAL_ERROR), clients should determine the state of the SubCampaign using the showSubCampaignState method and reference the SubCampaign using the externalId and Campaign fields. If this method returns an 'OBJECT_NOT_EXISTS' error then it is safe to retry, otherwise the client should stop the SubCampaign using changeSubCampaignState and then reattempt submission.

Errors

Error	Description
ARG_INVALID	Argument is invalid – reason '%s'
ARG_INVALID_DATA	Argument contains invalid data '%s'
ARG_INVALID_CHAR	Argument '%s' contains invalid characters
ARG_INVALID_FORMAT	Argument '%s' has an invalid format
ARG_INVALID_TYPE	Argument is of invalid type '%s'
ARG_NULL	Argument '%s' must be non-null
ARG_TOO_LARGE	Argument '%s' exceeds allowed size
ARG_TRUNCATED	Supplied argument value too long and truncated
ATTRIBUTE_INVALID	Attribute is invalid – reason '%s'
ATTRIBUTE_INVALID_DATA	Attribute contains invalid data '%s'
ATTRIBUTE_INVALID_CHAR	Attribute '%s' contains invalid characters
ATTRIBUTE_INVALID_FORMAT	Attribute '%s' has an invalid format
ATTRIBUTE_INVALID_TYPE	Attribute is of invalid type '%s'
ATTRIBUTE_NULL	Attribute '%s' must be non-null
ATTRIBUTE_TOO_SMALL	Attribute {0} is less than allowed minimum size.
ATTRIBUTE_TOO_LARGE	Attribute '%s' exceeds allowed size
ATTRIBUTE_TRUNCATED	Supplied attribute value too long and truncated
AUTHORIZATION_FAILURE	Authorization failure
INBOUND_DEVICE_ALREADY_MAPPED_TO_KEYWORD	Keyword "{0}" is already mapped to the short code "{1}".
INTERNAL_ERROR	Internal error
INVALID_STATE	Object in invalid State '%s' for operation
INVALID_OBJECT_TYPE	The supplied object '%s' is not of the correct type
INVALID_PASSWORD	Invalid Password
NO_SESSION	No current session
NOT_SUPPORTED	This operation is not supported
NOT_IMPLEMENTED	This operation is not implemented
OBJECT_EXISTS	Object '%s' already exists
OBJECT_NOT_EXISTS	Referenced object '%s' does not exist
RESULT_TOO_LARGE	Result returned would be too large '%s'
SYSTEM_LIMIT_EXCEEDED	Examples: Exceeded API call invocation rate
ACTIVE_RULE_SET_GROUPS_ASSOCIATED	Examples: Unable to delete ruleSetGroup '%s'.It's associated with active ruleSetGroups.