Skip to navigation

Asynchronous writes

What 202 Accepted means here, and how to confirm a write actually landed.
View as Markdown

Master Data accepts work and completes it later. Treating 202 as success is the single most common integration mistake.

What happens when you POST

1

Schema validation, synchronous

The payload is validated against the schema immediately. A malformed body returns 400 and nothing is queued. Retrying will not help; fix the body.

2

Acceptance: 202 with a location

A valid body returns 202 Accepted and a reference to the created resource in the Location header. This means “queued”, not “applied”.

3

Backend processing, asynchronous

The enterprise controller distributes the data, or the store handles it directly, depending on the scope you wrote at.

4

Confirmation: you poll

GET the location to read the resource’s current status.

A polling loop

import time
import requests
def wait_for_write(location, token, timeout=180):
    """Poll a Master Data location until it reports a terminal status."""
    deadline = time.monotonic() + timeout
    delay = 1.0
    while time.monotonic() < deadline:
        resp = requests.get(
            location,
            headers={"Authorization": f"Bearer {token}"},
            timeout=15,
        )
        if resp.status_code == 429:
            time.sleep(delay)
            delay = min(delay * 2, 30.0)
            continue
        resp.raise_for_status()
        status = resp.json().get("status")
        if status and status not in ("Pending", "InProgress"):
            return status
        time.sleep(delay)
        delay = min(delay * 1.6, 15.0)
    raise TimeoutError(f"{location} did not settle within {timeout}s")

Bound the wait. An unbounded poll turns a stuck write into a stuck worker.

Replays are safe

POSTs are insert-or-update keyed on object_id, so replaying a batch after an ambiguous failure converges rather than duplicating. This makes Master Data considerably easier to integrate than Register Sale, where you must track correlation IDs yourself.

“Safe to replay” is not “free to replay”. A replayed 2 MB batch still consumes rate-limit budget, so reconcile before resending rather than retrying on a timer.

Ordering across batches

Nothing sequences your batches for you. If batch B references entities created in batch A, wait for A to reach a terminal status before sending B. See load order.