HomeEngagementOther resources
API reference

Tracking API error messages

The Engagement Tracking API returns various error messages when requests fail or contain invalid data. This guide explains how the API reports errors, when to retry failed requests, and how to build integrations that handle failures effectively.

Error response structure

The Tracking API uses different response patterns depending on whether you're using batch endpoints or single-event endpoints.

Single-event endpoints

Single-event endpoints process one operation at a time and return errors immediately with 4xx status codes. When a request fails, the API returns a response with success: false and an errors array containing error messages:

{
  "success": false,
  "errors": ["At least one id should be specified."]
}

Common single-event endpoints include /customers for updating customer profiles and /customers/events for tracking individual events.

Batch endpoints

Batch endpoints allow you to send multiple operations together in a single request. The API may accept some operations while rejecting others, so error handling works differently than single-event endpoints.

When the entire batch request fails due to authorization or structural problems, the API returns a 4xx status code with success: false and a top-level error message:

{
  "success": false,
  "message": "Invalid JSON"
}

When the batch is accepted but individual commands fail, the API returns status 200 with success: true at the top level. Each command shows its own success status in the results array:

{
  "results": [
    {
      "success": true
    },
    {
      "success": false,
      "errors": [
        "At least one id should be specified."
      ]
    }
  ],
  "start_time": 1722458972.7475243,
  "end_time": 1722458972.7502902,
  "success": true
}

Command-level errors appear in the errors array as strings. You can identify which commands failed by checking the success property for each result.

How the API handles errors

The Bloomreach Engagement Tracking API returns errors at different stages of request processing. Understanding when and how errors occur helps you build more reliable integrations.

Immediate errors

The API catches and returns immediate errors when receiving your request. These errors relate to authorization problems or issues with request structure, and the API returns them directly in the response.

Authorization errors

Authorization errors occur when the API can’t authenticate your request or when your API key lacks the necessary permissions. Common authorization errors include incorrect project tokens, missing API keys, and insufficient permissions to track specific event types or update certain customer properties. The API returns these errors with 400, 401, or 403 status codes.

For detailed information about authorization error messages and how to resolve them, see the Authorization errors guide.

Request body errors

Request body errors occur after successful authentication of the request. You will receive request body errors when your request structure is invalid or missing required information. The API validates request formatting, required fields, and command structure before processing your data.

Common request body errors include empty command arrays, invalid JSON formatting, or missing customer IDs. Single-event endpoints return these errors with 400 status codes, while batch endpoints may return 200 status with command-level errors in the results array.

For detailed information about request body error messages and how to resolve them, see the Request body errors guide.

📘

Note

We recommend identifying and fixing authorization and request body errors during integration development and testing.

Data pipeline errors

Some errors occur after the API accepts your request (during data processing). These silent failures happen when:

  • Customer ID mismatches: Your tracked data contains customer IDs that don't exist in your project. For example, your project uses cookie and registered as ID types, but your request includes google_analytics or email. The API returns a successful response initially, but the data fails during processing.
  • Data Manager restrictions: Data Manager prevents tracking of new event types. Even when your API key has proper permissions and the API returns success, the system won't create the event in the customer profile.

📘

Note

These errors don't happen randomly. Identify and fix them during the integration and testing phases before moving to production.

Retry strategies

Use exponential backoff when retrying failed requests. This means waiting progressively longer between each retry attempt. For example:

  • Wait 1 second before the first retry,
  • 2 seconds before the second,
  • 4 seconds before the third, and so on.

This approach helps reduce pressure on the API during temporary problems.

Handling different status codes

  • Retry 5xx errors when you receive server errors like 500 Internal Server Error.
  • Retry 429 Too Many Requests after waiting for the time specified in the Retry-After header.
  • For batch requests with mixed results, when a batch request returns 200 status with success: false for specific commands, identify and retry only those failed commands. Review the error messages to understand the problem, fix it, then retry.
  • For batch requests with all successes, when a batch request returns 200 status with success: true, no retry is needed.
  • Treat socket_closed errors the same as timeouts and retry the request.

Deduplication protection

The API may accept your batch but respond with a timeout or error. When you retry in these situations, the deduplication system removes duplicate events automatically.

Best practices

  • Test thoroughly during integration: Send test data covering all your event types and customer ID combinations to catch data pipeline errors early.
  • Configure API key permissions correctly: Ensure your API keys have the right permissions for the events and properties you're tracking. Review authorization errors for guidance on permission-related issues.
  • Monitor for silent failures: During initial deployment, verify that events appear in customer profiles as expected. Check that all event types and customer IDs process successfully.
  • Implement proper error handling: Build retry logic into your integration using exponential backoff strategies. Log all errors for review and monitoring.
  • Use batch endpoints efficiently: Group related operations into batch requests to improve performance and reduce API calls.

Related resources

For detailed information about specific error types and how to resolve them, see: