The Salsa Engage API is a RESTful API that accepts and produces JSON payloads.
Error Codes Returned
There are two classifications of errors reported by the API
- System level errors which indicate that something went wrong with during the processing, your token is not valid, or you have exceeded the call rate configured for the token.
- Validation level errors when adding or updating supporter records
All system level errors will be reported as standard(or soon to be standard HTTP errors, following is the list of the errors you may encounter
|Bad Request - Directives in your payload were invalid||
This error would typically occur if the parameters for a search operation are not configured correct. Such an example is a activity search request without the modified From attribute set within the payload. In addition to the 400 code, the system will include a description for what the problem was. For example 200 Bad Request - Either 'modifiedFrom' or 'activityIds' must be provided.
|401||Unauthorized||Returned when a request without a valid token is made|
|429||Too Many Requests||
A 429 error code will be returned in one of two cases. Either the call rate for the token has been exceeded, or the batch size requested for an operation is larger than what is configured for your token.
In either case the 429 will be returned with either one of the following messages:
429 Call rate has been exceeded
429 Requested batch size exceeds the allowed size of: <token batch size value>
|500||Internal Server Error||
Non recoverable error has occurred.
This exception will also include a JSON structure in the body with additional contextual information which could be provided to Salsa for troubleshooting.
You should be aware that some of these errors reported in this manner can be resolved on your end. An example of such an error is providing an incorrect date format for a search condition.
Validation Codes Returned
Specific to Supporter management(E.g. Updates/Adds), the server will return contextual errors within an entity of a payload. These validation errors indicate that the values provided for the entity are not of the correct type, too large, or are missing.
Following is the list of validation error codes you may encounter:
|2001||Field Required||A value for the field identified within the error object is required|
|Field out of range||The value for the attribute is too long|
|Invalid Email Address||The provided email address appears to be invalid.|
The value provided was not one of the allowed types. The error message will indicate both the field in error as well as the allowed types
Validation Error for an Invalid Email Address
Understanding Available Calls Remaining
The API provides an endpoint that enables you to programmatically understand how many calls are available before making a request. The returned payload will include the count of available calls as well as operations that have been performed to date for the token.
- Your authentication token must be set in the HTTP header as parameter authToken=<your_auth_token>
|rateLimit||The rate limit configured for your token|
|maxBatchSize||The maximum number of items you can include for a batch call|
|currentRateLimit||Current point in time rate limit - how many calls that can be made before a 429 error will occur|
|supporterRead||Number of supporter reads|
|totalAPICalls||Number of API calls|
|lastAPICall||ISO_8601 formatted String with a GMT timezone|
|totalAPICallFailures||Number of API calls that failed|
|lastAPICallFailure||ISO_8601 formatted String with a GMT timezone|
|supporterRead||Supporter read count|
|supporterAdd||Supporter add count|
|supporterUpdate||Supporter update count|
|supporterDelete||Supporter delete count|
|activityEvent||Event activity read count|
|activitySubscribe||Subscribe activity read count|
|activityFundraise||Fundraise activity read count|
|activityTargetedLetter||Targeted Letter activity read count|
|activityPetition||Petition activity read count|
|activitySubscriptionManagement||Subscription Management read count|