Unexpected Data

When requests sent to the API include fields that are not expected within the defined structure (e.g., a field sent at the root level of event_data instead of within a nested object like meta), an error response may be returned. The API typically returns a status code indicating a validation failure, along with details about the unexpected field and suggestions for correction.

Example handling errors of the Track endpoint

The example below demonstrates how to handle errors related to unexpected data fields when using the track endpoint. In this case, passenger_token was sent directly within event_data instead of the meta object.

Request Body

{
    "event_name": "purchase_complete",
    "event_data": {
        "passenger_count": 2,
        "passenger_token": "azwer124",
        "payment_type": "credit_card",
        "trips_count": 1,
        "tickets": 2,
        "total": 31.00,
        "product": "web",
        "distinct_id": "1234567890",
        "email": "john.doe@example.com",
        "phone": "+12154567890",
        "trips": [
            {
                "departure_arrival": "2025-04-25T10:30:00-05:00",
                "departure_destination": "Boston",
                "departure_destination_terminal": "South Station",
                "departure_line": "Coastal Express",
                "departure_origin": "New York",
                "departure_origin_terminal": "Port Authority",
                "departure_price": 15.50,
                "departure_route": "NY-BOS",
                "departure_stop_cities": "New Haven",
                "departure_stops": 1,
                "departure_time": "2025-04-25T15:30:00-05:00",
                "departure_transporter": "East Coast Bus Company",
                "departure_transport_type": "bus",
                "bus_categories": "general"
            }
        ]
    }
}

Response

{
    "errors": [
        {
            "error_type": "UNEXPECTED_FIELD",
            "field": "passenger_token",
            "message": "The additional property passenger_token was sent.",
            "suggestion": "Make sure to send the passenger_token field in the meta parameter"
        }
    ],
    "message": "Validation failed. See details for more information.",
    "status": "error"
}

Solution

The solution involves moving the passenger_token field into the meta object within event_data.

{
    "event_name": "purchase_complete",
    "event_data": {
        "passenger_count": 2,
        "payment_type": "credit_card",
        "trips_count": 1,
        "tickets": 2,
        "total": 31.00,
        "product": "web",
        "distinct_id": "1234567890",
        "email": "john.doe@example.com",
        "phone": "+12154567890",
        "meta":: {
            "passenger_token": "azwer124"
        },
        "trips": [
            {
                "departure_arrival": "2025-04-25T10:30:00-05:00",
                "departure_destination": "Boston",
                "departure_destination_terminal": "South Station",
                "departure_line": "Coastal Express",
                "departure_origin": "New York",
                "departure_origin_terminal": "Port Authority",
                "departure_price": 15.50,
                "departure_route": "NY-BOS",
                "departure_stop_cities": "New Haven",
                "departure_stops": 1,
                "departure_time": "2025-04-25T15:30:00-05:00",
                "departure_transporter": "East Coast Bus Company",
                "departure_transport_type": "bus",
                "bus_categories": "general"
            }
        ]
    }
}

Behavior of the Identify endpoint

The identify endpoint behaves differently from the track endpoint regarding additional fields.

Note

Unlike the track endpoint, identify allows sending additional, custom fields directly within the profile_params object without causing an “Unexpected Field” error. These fields are stored as custom properties associated with the user profile.

Example

The following request includes an additional custom field loyalty_level within profile_params. This is acceptable and will be processed successfully by the identify endpoint.

{
    "profile_params": {
        "distinct_id": "1234567890",
        "first_name": "John",
        "last_name": "Doe",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+12154567890",
        "birthdate": "1990-01-01",
        "country_code": "US",
        "city": "New York",
        "loyalty_level": "gold"
    },
    "product": "web-mobile"
}

This request would typically result in a success response, as the API allows storing arbitrary custom data within the user’s profile via profile_params.