Messaging API error handling and retries

Messaging API response bodies and success semantics vary by endpoint. Use each endpoint’s response schema and status-code table as the authoritative contract.

Success responses

The Banner endpoints use different success responses:

• POST /v1/device-messaging/banners/sync returns a 200 status code with a banners object.
• POST /v1/device-messaging/banners/track returns a 202 status code with events_processed and message. If Braze skips individual events, the response also includes an errors array.

A 202 response from the tracking endpoint means Braze accepted at least one valid event. Review the errors array to identify skipped events.

Error responses

Error response fields also vary:

• Banner retrieval errors use an error field.
• Banner tracking errors use a message field and can include an indexed errors array.

Don’t parse error-message text to determine application behavior. Use the HTTP status code and endpoint-specific fields instead.

Retry guidance

Use the following guidance when deciding whether to retry:

Status code	Retry guidance
400	Correct the request before retrying. For Banner tracking, correct skipped events before retrying them.
401 or 403	Verify the client-side REST API key and its permissions before retrying.
404	Confirm that the Messaging API is enabled for the workspace and that the endpoint URL is correct.
429	Reduce the request rate and retry with exponential backoff. Use rate-limit response headers when available.
5XX	Retry with exponential backoff and a maximum number of attempts.

For the exact response body and supported status codes, refer to the relevant endpoint:

• Retrieve Banners for a user
• Track Banner analytics events