Skip to main content

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​

WriteSent again
POST /telemetryRewrites 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-logsCounts 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/configThe same document again answers 200 with the version it already has. Only a change stores a new version
POST /topology/demo-fleetSafe. 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 /predictionsStarts 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/scenariosStores another scenario
POST /predictions/runs/{run_id}/cancelSafe. It answers the same stopped run
POST /predictions/actions/{run_id}/{item_id}/approveSafe. It answers the same feed_cursor, or finishes publishing if the first try did not
POST /predictions/actions/{run_id}/{item_id}/reject409 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 sentWhen the answer did not arrive
TelemetrySend 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 logUpload it again
A runSend 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_unavailableIt 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-Key header 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.