View a markdown version of this page

Submitting reports - AWS Abuse Signal API

Submitting reports

AWS Abuse Signal API accepts abuse reports through an asynchronous API. This page covers the submission workflow in depth: idempotency, correlation IDs, tracking, pagination, and retry behavior. For a first end-to-end walkthrough, start with Getting started with AWS Abuse Signal API.

The submission workflow

  1. Build a valid eXtended Abuse Reporting Format (XARF) report. See Report format (XARF).

  2. Call CreateAbuseReport and receive 202 Accepted with a report ID.

  3. Persist the report ID and your correlationId so that you can track the report later.

  4. Poll GetAbuseReportStatus to track the report, or enumerate your submissions with ListAbuseReportStatuses.

Tracking status

GetAbuseReportStatus returns the current status, a human-readable description, and timestamps. When a report reaches the terminal COMPLETED status, it also carries a reasonCode describing the resolution outcome. Use GetAbuseReportStatus to read the current state for a given report ID.

A report progresses through the following states:

QUEUED -> PROCESSING -> COMPLETED
Status What it means

QUEUED

AWS has received your report and it is being queued for processing. Use the report ID to check the status of your report.

QUEUED (child sexual exploitation and abuse material reports)

AWS has received your report of suspected child sexual exploitation and abuse material.

Please also report this content directly to the National Center for Missing and Exploited Children’s (NCMEC) CyberTipline at the CyberTipline website. Do not send images or copies of the material to AWS.

PROCESSING

AWS has received your report and it is being processed. Use the report ID to check the status of your report.

COMPLETED

The service processed the report successfully. The status also carries a reasonCode describing the resolution outcome. See Resolution reason codes.

GetAbuseReportStatus is a waitable operation. If your SDK supports waiters, use the ReportProcessing waiter. It polls until the report reaches PROCESSING or COMPLETED, because a report can move from QUEUED to COMPLETED before a poll observes PROCESSING. The waiter treats ResourceNotFoundException as a transient "not yet propagated" signal and retries, which is useful immediately after submission, when the status record might still be propagating. A successful wait confirms that the service has started processing the report, not that the report is resolved.

If you poll GetAbuseReportStatus yourself, wait 1–5 seconds between calls, retry on ResourceNotFoundException, and accept either PROCESSING or COMPLETED. COMPLETED is the only terminal status.

Resolution reason codes

A COMPLETED report carries a reasonCode that describes the resolution outcome:

Reason code What it means

ACTIONED

The content or activity you reported has been mitigated.

If you believe the reported content or activity persists, submit a new report containing the relevant URLs or most recent activity logs.

NOT_RESOLVABLE_TO_AWS

AWS could not attribute the reported content or activity to AWS from the information provided.

If you’re able to provide additional information that may help us determine AWS as the origin, please submit a new report containing that information.

If no other information is available, you may use publicly available domain registration or network ownership information, including the WHOIS website to identify and contact the relevant registrar or IP owner.

REVIEWED_NO_AWS_ACTION

AWS has processed your report and isn’t taking further action at this time. If you have additional information, you can submit a new report that includes it.

CONTENT_DOWN_OR_INACCESSIBLE

The reported content or activity was not accessible when AWS checked it. If it is accessible now, submit a new report with the current URL or activity logs, and say if it is visible only from certain locations or after signing in.

NEED_MORE_INFORMATION

The report did not contain enough information to be processed. Required details vary by report type (for example, timestamps and IP/port data for activity reports, full headers for email spam, exact URLs for content reports).

Please submit a new report with as much information as possible.

Idempotency in depth

Because CreateAbuseReport returns 202 Accepted and the network can fail after the server has already accepted a report, retries are expected. Idempotency ensures that a retry does not create a duplicate. It works in one of two ways:

  • Client-provided token (recommended). Provide a clientToken (1–128 printable ASCII characters) that is unique per logical submission. Repeating the same token for the same principal returns the original report ID for 24 hours. This is the most predictable option and is recommended whenever your client can generate and remember a token.

  • Auto-generated token (default). If you omit clientToken, the service derives a token from a hash of the report payload and your principal, bucketed to a 5-minute window. Two identical payloads from the same principal within the same window collapse into one report. After the window, the service treats them as separate submissions.

Important

Reusing a clientToken with a different payload returns ConflictException (HTTP 409) rather than silently overwriting or duplicating. Choose a new token whenever the report content changes.

Correlation IDs

A correlationId (1–256 characters matching ^[a-zA-Z0-9-_]{1,256}$) is your own reference for the submission. The service echoes it back in responses, and you can use it to filter results in ListAbuseReportStatuses. Correlation IDs are not unique keys. Multiple reports can share one, so use them to group related submissions (for example, all reports from a single incident).

Submission requirements and rejections

A report can be rejected for two distinct reasons, and the HTTP status tells you which:

  • Not well-formed – The report fails the XARF schema or a field constraint. Returned as ValidationException (HTTP 400). Fix the structure or field values and resubmit.

  • Well-formed but disallowed – The report satisfies the schema but doesn’t meet a submission requirement. Returned as SubmissionRequirementException (HTTP 422). Retrying the same report does not succeed; you must change the report content.

A SubmissionRequirementException carries an unmetRequirements list. Each entry has a stable code, a path (a JSON Pointer to the offending member, or an empty string for the whole report), and a human-readable message. The service checks these requirements:

Code Applies to What it means and how to fix

rule.source_identifier.too_long

source_identifier

Longer than 253 bytes. This limit applies to every value, including URLs and IP addresses, and is checked before the format. If a URL exceeds the limit, supply only its hostname or IP address, and include the full URL in the report’s evidence.

rule.source_identifier.forbidden_characters

source_identifier

Contains {, }, *, or a backtick, which are never valid in an address and are common in injection payloads. Remove them.

rule.source_identifier.malformed

source_identifier

Not a valid IPv4 address, IPv6 address, URL, or domain name. Provide a well-formed identifier.

rule.timestamp.unparseable

timestamp

Not a valid RFC 3339 date-time. Use a format such as 2026-09-22T12:00:00Z.

rule.timestamp.in_future

timestamp

Dated further ahead than the clock-skew tolerance (default 1 hour). Check the reporting host’s clock.

rule.timestamp.too_old

timestamp

Earlier than the submission lookback window (default 90 days). For content that is still accessible, set the timestamp to the time you most recently observed it.

rule.evidence.content_type_mismatch

evidence

The decoded payload of an evidence item doesn’t match its declared content_type. The entry’s path identifies the item, for example /evidence/0. Set content_type to the file’s actual type, or replace the payload with a file of the declared type. For the supported types, see Embedded evidence.

Listing and pagination

ListAbuseReportStatuses returns up to maxResults items per page (1–50; a default page size applies when omitted). When more results exist, the response includes a nextToken. Pass it back on the next call to continue. You can also filter by correlationId. The service always scopes results to the caller’s own AWS account.

The following requests show the first and next pages. For a complete list request with authentication headers, see Step 4: List your reports.

GET /v1/abusestatuses?maxResults=25 HTTP/1.1 Host: abuse.us-east-1.amazonaws.com Authorization: AWS4-HMAC-SHA256 Credential=...

A successful call returns 200 OK with a page of reports in the reports array. When more results exist, the response also includes a nextToken.

{ "reports": [ { "reportId": "rpt01J5K9XMBN3QWERTY12345", "correlationId": "incident-2026-09-001", "status": "PROCESSING", "description": "Report has been received and is being processed." } ], "nextToken": "<token>" }

To retrieve the next page, pass the token back in the nextToken query parameter:

GET /v1/abusestatuses?maxResults=25&nextToken=<token> HTTP/1.1 Host: abuse.us-east-1.amazonaws.com Authorization: AWS4-HMAC-SHA256 Credential=...

The pagination parameters are:

  • maxResults – The maximum number of reports to return per page (1–50).

  • nextToken – The pagination token returned by the previous call. Omit it on the first call.

Retries and backoff

  • On 429 ThrottlingException or 500 InternalServerException, retry with exponential backoff and jitter, honoring the Retry-After header when present.

  • Always send the same clientToken on retries of the same logical submission so that the retry is idempotent.

  • Do not retry 400 (validation), 409 (conflict), or 422 (unmet submission requirement) without changing the request. These indicate a client-side issue to correct first.

For more information about the per-operation rate limits, see Quotas for AWS Abuse Signal API.