# Writes, versions, and retries

Source: https://neondeerdata.com/docs/api/requests/

Use current versions and request keys, and follow work after it is accepted.

## Read before changing a resource

Get the resource before changing it. When a route requires `expected_version`, send the version from that read without incrementing it yourself. Versions can be strings or integers; use the type shown for that endpoint.

A workflow can also require its current target version and Attio workflow version. A merge execution requires the exact plan revision, its returned digests, and current authorization versions. Copy these values from the relevant read response; do not manufacture them.

## Request keys

For a write whose reference requires a request key, send it in the REST `Idempotency-Key` header. The same value is the `request_key` argument in MCP. Other writes, including lookup-row PATCH and DELETE, do not use this mechanism. Follow the operation’s reference.

Generate a new value for a new intended action. Keep the same value and request content when retrying an action after a lost response or timeout. Reusing a key for a different request can be refused. Creating a fresh key for every retry can repeat the effect.

Lookup-row writes and other API families can have different retry behavior. The operation's reference describes what is replayed. Retrying an accepted request is not a rollback, and work completed before a timeout can remain.

## Follow accepted work

An HTTP `202` response means work was accepted. Follow its returned operation or status resource until it finishes. A successful operation can still contain unsuccessful items; inspect those outcomes before retrying them.

Use [operation status](https://neondeerdata.com/docs/api/operations/) for scans, merge work, and other requests that return an operation. Table configuration work can instead be followed through the table settings and `pending_work`; CSV imports have their own status resource.

## Handle conflicts and partial results

If a resource changed, get it again and review the new state before repeating a write. Do not automatically replace the expected version with the latest one without checking what changed.

Inspect each item's outcome in a batch response. Stopping an import or canceling remaining work does not undo changes that completed. A request that reports an uncertain result needs inspection before a new attempt.

## Rate limits and temporary failures

Use `Retry-After` when returned and back off between retries. Inspect the current state after a write whose response was lost. See [rate limits](https://neondeerdata.com/docs/api/rate-limits/) and [errors](https://neondeerdata.com/docs/api/errors/). Do not retry authentication, permission, or invalid-input errors unchanged.