Introduction
An HTTP 400 Bad Request response from a Bloomreach Engagement Marketing API endpoint usually indicates that the request could not be processed because its format or content does not meet the endpoint’s requirements. The response body can help determine whether the issue originated with the API endpoint or an intermediary.
The exact cause depends on the API endpoint and the error message in the response body. Use the steps below to identify and correct the request.
Common causes
Invalid JSON format
The request body is not valid JSON. Common examples include:
A missing or extra comma
An opening or closing brace or bracket is missing
A property name is not enclosed in double quotes
A string contains an unescaped character
The request body is empty or truncated
Validate the complete request body with a JSON validator before sending it again.
Missing required fields or parameters
The JSON can be syntactically valid yet still fail validation if a required field is missing or a transactional email template parameter is not included in the request (see example below).
Compare your request with the requirements for the specific endpoint. Check the required fields, parameter names, data types, and nesting structure.
Invalid IDs or object references
Some endpoints return HTTP 400 when the request contains an invalid object ID, integration ID, or email template ID. Confirm that the ID exists, belongs to the correct project, and is used in the correct field.
Catalog fields are not defined
Catalog update requests can return HTTP 400 when they reference item properties that do not exist in the catalog. Define the properties in the catalog before you use them in an update request.
The request body is compressed unexpectedly
Some clients or proxies automatically compress the request body with gzip. If the response contains a message similar to BadRequest: The browser (or proxy) sent a request that this server could not understandcheck whether gzip compression is enabled for the request body.
Disable automatic gzip compression and send the uncompressed JSON body.
How to troubleshoot the error
-
Read the complete response body.
The response often identifies the problem, for example
Invalid JSON,Missing params,Fields are not properly defined,Could not parse <id>, orTemplate <id> not found.
-
Identify the API endpoint and HTTP method.
Open the documentation for the exact endpoint you call. Do not compare the request with an example from a different API, such as the Tracking API, Customer API, Catalog API, Channel API, or Transactional Email API.
-
Validate the request body.
Run the complete body through a JSON validator. Then compare the structure with the endpoint documentation, including required fields, parameter names, value types, and nesting.
-
Check the request headers.
For JSON requests, verify that the request uses the expected
Content-Type, normallyapplication/json. Check that your client, proxy, or middleware does not modify or compress the body before transmission. -
Verify IDs and configuration.
Confirm that referenced customer IDs, catalog fields, integration IDs, templates, and other objects exist in the relevant project and that the API group has the required permissions.
-
Test the corrected request from a backend client.
Use your server-side integration or a tool such as Postman to send the request again. Do not expose API keys or secrets in browser code, screenshots, logs, or support requests.
Example: valid JSON does not guarantee a valid request
The following body is valid JSON, but it can still return HTTP 400 if the endpoint requires a field that is missing or does not support one of the supplied properties:
{
"customer_ids": {
"registered": "customer-10482"
},
"event_type": "order_completed",
"properties": {
"order_id": "order-2026-0815"
}
}Run the complete body through a JSON validator. Use the endpoint documentation to confirm whether the endpoint accepts these fields and whether it requires additional data. A JSON validator checks syntax; it does not verify the business rules of a Bloomreach API endpoint.
Summary
An HTTP 400 error means that Bloomreach Engagement cannot process the request as sent. Start by reading the response body, validating the JSON, checking required fields and referenced IDs, and confirming the request headers and compression settings. If the error continues, share the sanitized request details with Bloomreach Support for further investigation.
When to contact Bloomreach Support
Contact Support if the request still returns HTTP 400 after you validate the JSON, compare it with the endpoint documentation, and verify the referenced objects.
Include the following details:
The Bloomreach Engagement project and environment
The API endpoint and HTTP method
The approximate time of the failed request and the affected timezone
The complete HTTP status and response body
A sanitized request body
The tool, SDK, or server library that sends the request
A request ID or correlation ID, if the response provides one
Remove API keys, API secrets, authorization headers, customer personal data, and other sensitive information before sharing request details.