API errors and responses

This reference article covers the various errors and server responses that can come up while using the Braze API and how to troubleshoot them.

Server responses

If your POST payload was accepted by our servers, then successful messages will be met with the following response:

1
2
3
{
  "message" : "success"
}

Note that success only means that the RESTful API payload was correctly formed and passed onto our push notification or email or other messaging services. It does not mean that the messages were actually delivered, as additional factors could prevent the message from being delivered (for example, a device could be offline, the push token could be rejected by Apple’s servers, you may have provided an unknown user ID).

If your message is successful but has non-fatal errors you will receive the following response:

1
2
3
{
  "message" : "success", "errors" : [<minor error message>]
}

In the case of a success, any messages that were not affected by an error in the errors array will still be delivered. If your message has a fatal error you will receive the following response:

1
2
3
{
  "message" : <fatal error message>, "errors" : [<minor error message>]
}

Responses for tracked send IDs

Analytics are always available for campaigns. In addition, analytics are available for a specific campaign send instance when the campaign is sent as a broadcast. When tracking is available for a specific campaign send instance, you will receive the following response:

1
2
3
{
  "message": "success", "send_id" : "example_send_id"
}

The provided send id can be used as a parameter for the /send/data_series endpoint to pull back send specific analytics.

Errors

The status code element of a server response is a 3-digit number where the first digit of the code defines the class of response.

• The 2XX class of status code (non-fatal) indicates that your request was successfully received, understood, and accepted.
• The 4XX class of status code (fatal) indicates a client error. Refer to the fatal errors chart for a full list of 4XX error codes and descriptions.
• The 5XX class of status code (fatal) indicates a server error. There are several potential causes, for example, the server you’re trying to access is unable to execute the request, the server is undergoing maintenance making it unable to execute the request, or the server is experiencing high levels of traffic. When this happens, we recommend you retry your request with exponential backoff. In the event of an incident or outage, Braze is not able to replay any REST API call that failed during the incident window. You will need to retry any calls that failed during the incident window.

Fatal errors

The following status codes and associated error messages will be returned if your request encounters a fatal error.