Idempotency: retrying writes safely
What a write does when you send it again depends on the route: telemetry and pass logs land on the same records, a network config that has not changed keeps its version, a run started with an Idempotency-Key is started once, and workflow saves and scenarios are new each time. POST /predictions is the one route that takes an Idempotency-Key header.
What a repeated write does
| Write | Sent again |
|---|---|
POST /telemetry | Rewrites the same points. A record is identified by its ground station, antenna, satellite, radio, dataset and time, so a replayed batch adds no duplicates |
POST /telemetry/pass-logs | Counts each contact once. A contact is its satellite, antenna and AOS; uploading the log again rewrites the same contacts |
PUT /telemetry/files/{source}/{name} | Stores a second copy. Every upload is a new file named by when it arrived; compare sha256 to spot a repeat |
PUT or PATCH /topology/config | The same document again answers 200 with the version it already has. Only a change stores a new version |
POST /topology/demo-fleet | Safe. It keeps the demo fleet, adds only what it lacks, and writes its telemetry again to end now |
PUT /predictions/workflows/{slug} | Saves another version, even of the same graph |
POST /predictions | Starts another run, unless it carries the same Idempotency-Key: the same key and body within 30 days answers 200 with the first run's run_id and status, and the same key with another body is 409 idempotency_key_reused |
POST /topology/scenarios | Stores another scenario |
POST /predictions/runs/{run_id}/cancel | Safe. It answers the same stopped run |
POST /predictions/actions/{run_id}/{item_id}/approve | Safe. It answers the same feed_cursor, or finishes publishing if the first try did not |
POST /predictions/actions/{run_id}/{item_id}/reject | 409 action_decided: a decision is made once |
Partial acceptance
POST /telemetry writes every record that passes its checks and answers 202 with what it did not write:
{
"write_id": "8c41f2ae-5d0b-4c7e-9a51-3e2f6b7d9c10",
"accepted_count": 118,
"rejected_count": 2,
"rejected_indices": [4, 87],
"rejections": [
{ "index": 4, "field": "satellite_id", "reason": "not_in_network_config" },
{ "index": 87, "field": "es_n0_db", "reason": "wrong_type" },
{ "index": 90, "field": "snr_margin", "reason": "unknown_field" }
]
}
rejected_indices are the records not written. rejections lists every problem, including an unknown field dropped from a record that was written, such as index 90 above. Fix the rejected records and send only those; sending the accepted ones too does no harm, since they rewrite the same points. The batch is refused whole with 400 invalid_input when no record passes, and with 422 when a record does not match the record schema.
A pass log is all or nothing instead: a log with a bad row writes none of it and answers 422 invalid_pass_log, one problem per row. A row that logs a contact twice in one file is a duplicate_contact problem.
Retry after a timeout
| You sent | When the answer did not arrive |
|---|---|
| Telemetry | Send the same batch again with the same times. Records stamped up to 5 minutes in the future are shifted back with the other records of their series in that batch, the latest to when they arrive, so their replay lands at new times, and records further ahead are rejected as implausible_timestamp: stamp records with when they were measured |
| A pass log | Upload it again |
| A run | Send it again with the same Idempotency-Key and body: the answer is the first run. Without a key, read the workflow's active_run with GET /predictions/workflows/{slug} before starting another. A 202 with a note means the run may still start: poll its run_id rather than start a second |
A run refused with 503 sim_runs_unavailable | It never started. Start it again |
Never retry 400 field_type_conflict or a 403: the answer does not change. The rules for every status are in Errors and limits.
The usage count on your account counts each accepted telemetry point when it is written, so a replay is counted again. It is for display only: no plan is capped or charged by it.
Deliveries you receive
What Constellation sends you is safe to receive twice:
- A webhook request carries an
Idempotency-Keyheader that stays the same when it is delivered again: a workflow run's<run_id>:<destination_id>:<part>, or the delivery's own id for served forecasts. Drop a request whose key you have already applied. See Webhooks and SDKs. - An S3 object delivered again overwrites the same key, and a Grafana point lands on the same sample.
- A connector keys results by pass, so a newer run updates what it wrote instead of adding a copy, and a run published again keeps its first entry in your workflow results and its cursor. See the results protocol.