Diagnostics

Page Summary

outlined_flag

• Issue requests to send events or manage audience members.

• Check the overall status of each request, modifying and resending if unsuccessful.

• Send a RetrieveRequestStatus request for successful requests using the captured request_id.

• Review the RetrieveRequestStatusResponse to confirm uploads are working and identify data issues.

• Correct data issues and repeat the process until all issues are resolved.

Here's the recommended workflow to verify the health of your event and audience uploads and identify issues with your data.

1. Issue requests to send events or send or remove audience members .

2. Check the overall status of each request. A successful request has a Status with code equal to 0 (enum value OK , HTTP response 200 OK ), and returns a IngestEventsResponse , IngestAudienceMembersResponse , or RemoveAudienceMembersResponse .

   If a request isn't successful, modify the request to address the error and send the request again.

   If a request succeeds, capture the response's request_id so you can use it to retrieve diagnostics in the next step.

3. Wait for 30 minutes, then send a RetrieveRequestStatus request for each successful request_id .

   Periodically repeat this step for each request_id until the destination status for each destination reaches SUCCESS , PARTIAL_SUCCESS , or FAILURE . Use an exponential backoff algorithm to wait between each request.

4. Review each RetrieveRequestStatusResponse to confirm your uploads are working properly and identify any issues with your data.

5. Correct data issues.

6. Go back to step 1 and repeat until you've addressed all issues with your uploads.

Send requests

A RetrieveRequestStatusRequest requires a single request_id value. Send a separate status request for each request ID you captured from a successful ingestion request.

Periodically send the RetrieveRequestStatusRequest using an exponential backoff algorithm until the request_status reaches SUCCESS , FAILURE , or PARTIAL_SUCCESS for every destination in the original request. This may take up to 24 hours, although the Data Manager API may finish processing some requests in as little as 30 minutes.

Here's an example of a reasonable initial wait time and retry configuration that balances liveness and quota usage:

Setting	Value
Wait time before first diagnostics request (minutes)	30
Backoff multiplier	1.3
Maximum backoff (minutes)	60 (1 hour)
Maximum total time (minutes)	1440 (24 hours)

Here's a sequence of requests and elapsed time with this configuration:

Add a small random amount of jitter to the backoff delays to prevent the "thundering herd" problem where many clients retry simultaneously.

Review responses

The request_status_per_destination in a RetrieveRequestStatusResponse contains a separate entry for each destination in the corresponding ingestion request.

For example, if your IngestAudienceMembersRequest contained 3 entries in the destinations list to send data to 3 different audiences, then the status response would contain 3 entries in request_status_per_destination (one entry per audience).

Check overall destination status

As a first step, check the request_status field to determine if the Data Manager API has finished processing the data for the destination of the RequestStatusPerDestination .

Here are the possible values of request_status :

• PROCESSING : The data for the destination is still being processed. The warnings and errors aren't populated for the destination at this stage.

• SUCCESS : Request processing for the destination completed without any errors. Check for warnings flagged during processing.

• FAILURE : All of the records for the destination failed due to errors. Check for warnings and errors to determine why all records failed. Also check for warnings flagged during processing.

• PARTIAL_SUCCESS : Some of the records for the destination succeeded, but others failed due to errors. Check for errors to determine why some records failed. Also check for warnings flagged during processing.

Check event or audience status per destination

Inspect the status field that corresponds to the type of ingestion request. Only one of the following fields is set on each RequestStatusPerDestination :

• events_ingestion_status
• audience_members_ingestion_status
• audience_members_removal_status

Events ingestion status

The events_ingestion_status field is populated if the request was an IngestEventsRequest .

Check the record_count of the IngestEventStatus to confirm that the total number of records received matches your expectations. The record_count includes both successful and failed records.

Audience members ingestion status

The audience_members_ingestion_status field is populated if the request was an IngestAudienceMembersRequest . Here's the IngestAudienceMembersStatus field to check for each type of audience data. Only one of these fields is set.

user_data_ingestion_status

Check the record_count of the IngestUserDataStatus to confirm that the total number of records received matches your expectations. The record_count includes both successful and failed records.

Check the user_identifier_count to confirm the number of user identifiers received matches your expectations.

If the request had a sufficient number of records, the upload_match_rate_range contains the match rate range for records in the request.

mobile_data_ingestion_status

Check the record_count of the IngestMobileDataStatus to confirm that the total number of records received matches your expectations. The record_count includes both successful and failed records.

Check the mobile_id_count to confirm the number of mobile IDs received matches your expectations.

pair_data_ingestion_status

Check the record_count of the IngestPairDataStatus to confirm that the total number of records received matches your expectations. The record_count includes both successful and failed records.

Check the pair_id_count to confirm the number of PAIR IDs received matches your expectations.

ppid_data_ingestion_status

Check the record_count of the IngestPpidDataStatus to confirm that the total number of records received matches your expectations. The record_count includes both successful and failed records.

Check the ppid_count to confirm the number of PPIDs received matches your expectations.

user_id_data_ingestion_status

Check the record_count of the IngestUserIdDataStatus to confirm that the total number of records received matches your expectations. The record_count includes both successful and failed records.

Check the user_id_count to confirm the number of user IDs received matches your expectations.

composite_data_ingestion_status

Check the record_count of the IngestCompositeDataStatus to confirm that the total number of records received matches your expectations. The record_count includes both successful and failed records.

Check the data_type_counts to confirm that the number of identifiers matches your expectations. This list provides a breakdown of all identifiers received (such as email address, phone number, physical address, and IP address) by DataType .

If the request had a sufficient number of records, the upload_match_rate_range contains the match rate range for records in the request.

Audience members removal status

The audience_members_removal_status field is populated if the request was a RemoveAudienceMembersRequest . Here's the RemoveAudienceMembersStatus field to check for each type of audience data. Only one of these fields is set.

user_data_removal_status

Removal status for user data .

mobile_data_removal_status

Removal status for mobile data .

pair_data_removal_status

Removal status for PAIR data .

ppid_data_removal_status

Removal status for PPID data .

user_id_data_removal_status

Removal status for User ID data

composite_data_removal_status

Removal status for Composite data

Check the record_count to confirm that the total number of records received matches your expectations. The record_count includes both successful and failed records.

In addition, check the user_identifier_count , mobile_id_count , pair_id_count , ppid_count , or user_id_count to confirm the total count of identifiers received.

For composite data, check the data_type_counts to confirm that the number of identifiers matches your expectations. This list provides a breakdown of all identifiers received (such as email address, phone number, physical address, and IP address) by DataType .

Check warnings and errors

In addition to the status fields for the destination and request type, the RetrieveRequestStatusResponse contains a breakdown of warnings and errors for the request.

• An error indicates that the API completely rejected the record.
• A warning indicates that the API didn't reject the record, but it had to ignore portions of the record's data.

For example, if an Event contains encrypted UserIdentifier data and AdIdentifiers such as gclid , and the UserIdentifier data can't be decrypted, the Data Manager API still processes the record using the AdIdentifiers but returns the warning PROCESSING_WARNING_REASON_USER_IDENTIFIER_DECRYPTION_ERROR .

However, if the Event doesn't contain AdIdentifiers and the UserIdentifier data can't be decrypted, the Data Manager API rejects the entire record and reports the error PROCESSING_ERROR_REASON_USER_IDENTIFIER_DECRYPTION_ERROR because a valid Event must have at least one of ad_identifiers or user_data .

Here are the response fields that contain warning and error information. These fields are populated when the overall destination status reaches SUCCESS , PARTIAL_SUCCESS , or FAILURE .

warning_info

A list of WarningCount objects. Each WarningCount contains a reason with the type of warning, and a record_count indicating the number of records that had that type of warning.

Check the warning_info even if the overall destination status is SUCCESS .

error_info

A list of ErrorCount objects. Each ErrorCount contains a reason with the type of error, and a record_count indicating the number of records that failed due to that type of error.