Troubleshooting webhook and Connected Content requests

This article covers how to troubleshoot common error codes for webhooks and Connected Content, and provides further explanations on how these errors can occur in your requests.

4XX errors

4XX errors indicate that there’s an issue with the request sent to the endpoint. These errors are typically caused by erroneous requests, including malformed parameters, missing authentication headers, or incorrect URLs.

Refer to the following table for error code details and steps to resolve:

Error code	What it means	Steps to resolve
400 Bad Request	There's invalid syntax in the request.	Check the request payload for any syntax errors. Confirm that all required fields are included and correctly formatted. If you're sending a JSON payload, validate the JSON structure.
401 Unauthorized	The request requires user authentication.	Verify that the correct authentication credentials (such as API keys or tokens) are included in the request headers. Confirm that you have the user permissions to access the endpoint.
403 Forbidden	The endpoint understands the request but refuses to authorize it.	Check if the API key or token has the required permissions. Confirm that you have the user permissions to access the endpoint.
404 Not Found	The endpoint cannot find the requested resource.	Check the endpoint URL for any typos or incorrect paths. Confirm that the resource you're trying to access exists.
405 Method Not Allowed	The request method is known by the endpoint but is not supported by the target resource.	Check the HTTP method (DELETE, GET, POST, PUT) used in the request. Confirm that the endpoint supports the method you're using.
408 Request Timeout	The endpoint timed out processing the request.	Check the HTTP method (DELETE, GET, POST, PUT) used in the request. Confirm that the endpoint supports the method you're using.
409 Conflict	The request is incomplete because of a conflict with the current state of the resource.	Check the HTTP method (DELETE, GET, POST, PUT) used in the request. Confirm that the endpoint supports the method you're using.
429 Too Many Requests	There are too many requests sent in a given amount of time.	Lower the rate limit on your campaign or Canvas step.

5XX errors

5XX errors indicate that there’s an issue with the endpoint. These errors are typically caused by server-side issues.

Error code	What it means
500 Internal Server Error	The endpoint encountered an unexpected condition that prevented it from completing the request.
502 Bad Gateway	The endpoint received an invalid response from the upstream server.
503 Service Unavailable	The endpoint is currently unable to handle the request due to a temporary overload or maintenance.
504 Gateway Timeout	The endpoint didn’t receive a timely response from the upstream server.
599 Connection Error	Braze experienced a network connect timeout error while trying to establish a connection to the endpoint, meaning the endpoint may be unstable or down.

Resolving 5XX errors

Here are tips for troubleshooting common 5XX errors:

• Review the error message for specific details available in the Message Activity Log. For webhooks, go to the Performance Over Time section on the Braze home page and select the statistics for webhooks. From here, you can find the timestamp that indicates when the errors occurred.
• Make sure you’re not sending too many requests that overload the endpoint. You can send in batches or adjust the rate limit to check if this reduces any errors.