error-codes-and-mitigation.md

Error Codes and Mitigations for Aggregation Service

Aggregation Service Return Codes and Mitigations

This section covers the return code provided by the Aggregation Service job once it finishes running. The return_code field within the result_info section of the getJob API response will provide these return codes listed in /docs/api.md#getjob-endpoint.

Return Code	Message	When does this error happen?	Job can be retried	Adtech actionable?	Mitigation
SUCCESS	Aggregation Job completed successfully.	Aggregation Job completed successfully.	N/A	N/A	N/A
SUCCESS_WITH_ERRORS	"Aggregation job successfully processed but some reports have errors."	Some of the reports had processing errors.	No	No	Check the Error Summary to see Aggregation Service Report Error Codes. More details about error summary at /docs/api.md#error-response-body-1
PRIVACY_BUDGET_EXHAUSTED	"Insufficient privacy budget for one or more aggregatable reports. No aggregatable report can appear in more than one aggregation job."	When a job is trying to process reports that have been processed before or have the same shared ID as another report that is already processed.	No	Yes	Remove reports that have shared IDs with no budget left. Note: All reports regardless of production or debug endpoint will need to be batched according to shared ID. If you have a batch where the shared ID both exists in production and debug, you will encounter a privacy budget exhausted error. See our batching strategies /docs/batching-strategies.md for more information.
PRIVACY_BUDGET_ERROR	"Exception while consuming privacy budget. Exception message: " + {exception message}	An error happened while consuming the privacy budget.	Yes	Yes	Retry the job. We also recommend each batch to be per advertiser or destination. Batching strategies can be found at /docs/batching-strategies.md
INVALID_JOB	"Error due to validation exception."	When the job parameters fail validation.	Yes	Yes	Correct the job parameters for the job based on the validation message returned. Please see the createJob request parameter documentation for more details : /docs/api.md#payload
RESULT_WRITE_ERROR	"Exception occured while writing result."	When the write to the output directory fails.	No	Yes	1. Check that the account running Aggregation Service has write permissions for the output directory. 2. If a budget recovery process is available then contact Aggregation Service support for recovering the budget.
INTERNAL_ERROR	"Exception in processing domain." or "Internal Service Exception when processing reports."	An error occurred while processing output domains or Internal Error encountered.	Yes	Yes	Ensure that output domain location is a valid path. Retry the job. If error persists, contact Aggregation Service support.
UNSUPPORTED_REPORT_VERSION	"Exception due to unsupported report version"	An aggregatable report with a higher major sharedInfo version was provided and Aggregation Service is not up-to-date to support this version.	No	Yes	Update Aggregation Service deployment to a version that supports the report versions.
PERMISSION_ERROR	"Exception because of missing permission."	Aggregation service did not have access to storage or other requested resources.	No	Yes	1. Ensure that Aggregation Service has access to the storage and requested resources to run the job. 2. This could be due to permission error while fetching decryption keys. Ensure that the account running Aggregation Service is the same as the one provided during onboarding.
INPUT_DATA_READ_FAILED	"No report shards found for location: " + reportsLocationor "Exception while reading reports input data." or "Exception while reading domain input data."	No reports or output domain shards were found, or the Aggregation Service was unable to read them.	Yes	Yes	1.Ensure that the input report data location has the reports to be processed. 2.Ensure that the job has the right permissions to read the input/domain shards. Make sure the worker/job has the correct permissions to read the shards. 3.Ensure that the input_data_bucket_name, input_data_blob_prefix, output_data_bucket_name and output_data_blob_prefix fields are correct in your createJob request
DEBUG_SUCCESS_WITH_PRIVACY_BUDGET_ERROR	"Aggregation would have failed in non-debug mode due to a privacy budget error."	Job run using debug_run param succeeded but would have failed due to privacy budget error if run in normal mode.	Yes	No	N/A
DEBUG_SUCCESS_WITH_PRIVACY_BUDGET_EXHAUSTED	"Aggregation would have failed in non-debug mode due to privacy budget exhaustion"	Job running in Debug Mode succeeded but would have failed if running in non-debug mode due to privacy budget exhaustion.	Yes	No	N/A
REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD	"Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold."	The number reports with an issue exceeded the threshold.	Yes.	Yes	Check the Error Summary to see Aggregation Service Report Error Codes. Retry the job once reports with errors are removed from the batch.
PRIVACY_BUDGET_AUTHENTICATION_ERROR	"Aggregation service is not authenticated to call privacy budget service. This could happen due to a misconfiguration during enrollment. Please contact support for resolution."	Aggregation Service is not set up correctly for Aggregatable report accounting.	Yes, retry after setup is fixed.	Yes	Check that the account running the Aggregation Service matches the account that was provided during onboarding.
PRIVACY_BUDGET_AUTHORIZATION_ERROR	"Aggregation service is not authorized to call privacy budget service. This could happen if the createJob API job_paramaters.attribution_report_to does not match the one registered at enrollment. Please verify and contact support if needed."	The attribution reporting origin in the job parameters doesn't match the one registered during enrollment.	Yes, retry after changing the reporting origin job parameter.	Yes	Correct the job parameter attribution_report_to.

Aggregation Service Report Error Codes and Mitigations

This section covers the report-level errors present in the error summary. These are reports excluded from aggregation due to errors and can be found in the getJob response result_info.error_summary.error_counts. See /docs/api.md#error-response-body-1 for more details.

Return Code	Message	When does this error happen?	Mitigation
DECRYPTION_KEY_NOT_FOUND	"Could not find decryption key on private key endpoint."	The key_id supplied in the report's payload was not found.	For Attribution Reporting API, this error may be caused by an issue with the trigger registration. Check that the trigger has been registered with the correct cloud using the aggregation_coordinator_origin field (instructions here: AGGREGATE.md#data-processing-through-a-secure-aggregation-service in github.com/WICG/attribution-reporting-api). This can also happen when aggregatable reports encrypted for one cloud are aggregated with an Aggregation service running on another cloud provider. Validate the public key endpoint used to encrypt the aggregatable reports. On your raw aggregatable report received in your .well-known reporting endpoint, you should be able to see the aggregation_coordinator_origin field. For GCP, the value should be https://publickeyservice.msmt.gcp.privacysandboxservices.com. For AWS, it's https://publickeyservice.msmt.aws.privacysandboxservices.com. If aggregation_coordinator_origin is not stated in the Attribution Reporting API / Private Aggregation API, the default will be AWS. For Attribution Reporting API, you can specify your cloud provider by passing it in the trigger registration. For Private Aggregation API, you will have to define the aggregationCoordinatorOrigin using the example in Aggregation coordinator choice section in the Private Aggregation API explainer. Please specify https://publickeyservice.msmt.gcp.privacysandboxservices.com as the "aggregationCoordinatorOrigin".
DECRYPTION_KEY_FETCH_ERROR	"Fetching the decryption key for report decryption failed. This can happen using an unapproved aggregation service binary, running the aggregation service binary in debug mode, key corruption or service availability issues."	This happens if running an unapproved Aggregation Service binary or due to Key Service issues.	No action required in case of Key Service disruptions. Job can be retried. In case of unapproved binary, using the right binary will fix the issue. Follow instructions here to use prebuilt image or self-build your image: /docs/aws-aggregation-service.md#download-terraform-scripts-and-prebuilt-dependencies
DECRYPTION_ERROR	"Unable to decrypt the report. This may be caused by: a tampered aggregatable report file, a corrupt encrypted report, or other such issues."	This happens when report decryption fails.	1. Ensure that the Aggregatable AVRO reports are generated correctly. Payload will need to be base64 decoded and converted into a byte array. More information on how to generate an AVRO report can be found at /docs/collecting.md#convert-the-aggregatable-report-into-avro-binary-representation 2. Ensure that the report is in avro format. 3.Check if the output domain AVRO is correct. Buckets are converted to escaped unicode hex format and then converted into a byte array. Contact Aggregation Service support for next steps.
ATTRIBUTION_REPORT_TO_MALFORMED	Report's reporting_origin domain is malformed. Domain must be syntactically valid and have an Effective Top Level Domain (eTLD).	This happens when the reporting origin's domain is malformed/invalid.	Ensure that the reports have a valid reporting origin domain.
ATTRIBUTION_REPORT_TO_MISMATCH	Report's reporting_origin value does not match attribution_report_to value set in the Aggregation job parameters. Aggregation request job parameters must have attribution_report_to set to report's reporting_origin value.	This occurs when there is a mismatch between the report's origin and the aggregation job parameters.	Change the reporting origin in the job parameter attribution_report_to to match the reporting origin of the reports being processed.
DEBUG_NOT_ENABLED	"Reports without .debug_mode enabled cannot be processed in a debug run."	This happens when the job is trying to process reports without debug mode enabled in a debug run.	Process only debug mode enabled reports in the debug run. A debug run only considers reports that have the flag "debug_mode": "enabled" in the report shared_info, see example at: collecting.md#aggregatable-report-sample
NUM_REPORTS_WITH_ERRORS	"Total number of reports had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons.	This indicates that some reports had errors and were excluded from aggregation.	Exclude the processed reports and rerun the job with the unprocessed reports.
ORIGINAL_REPORT_TIME_TOO_OLD	"Report's scheduled_report_time is too old, reports cannot be older than 90 days."	This error occurs when the report's timestamp is older than the allowed 90-day limit.	N/A - The reports are too old to be processed.
INTERNAL_ERROR	"Internal error occurred during operation."	An internal error within the Aggregation Service service during operation.	Retry the job. If you encounter repeated Internal Errors, contact Aggregation Service support for help.
UNSUPPORTED_OPERATION	"Report's operation is unsupported. Supported operations are {SUPPORTED_OPERATIONS}."	This means that the report's operation is not among the supported operations.	N/A - The report's operation is not supported by Aggregation Service.
UNSUPPORTED_REPORT_API_TYPE	"The report's API type is not supported for aggregation. Supported APIs are {SUPPORTED_APIS}"	This error occurs when the report's API type is not supported by Aggregation Service.	N/A - The report's API type is not supported by Aggregation Service.
REQUIRED_SHAREDINFO_FIELD_INVALID	"One or more required SharedInfo fields are empty or invalid."	This indicates that essential SharedInfo fields are missing or contain invalid values.	Ensure that the reports have all the required SharedInfo fields.
INVALID_REPORT_ID	"Report ID missing or invalid in SharedInfo."	This error happens when the report ID is missing or invalid in the SharedInfo.	N/A - Aggregation Service cannot process reports with invalid report ID.
UNSUPPORTED_SHAREDINFO_VERSION	"Report has an unsupported version value in its shared_info. Supported values for report shared_info major version(s) are:{SUPPORTED_MAJOR_VERSIONS}"	This error arises when the report's shared_info version is incompatible with the supported versions.	Process the reports with a version of Aggregation Service that supports the report versions.