Creating resources (POST)
Always send an idempotency key
Include a unique
x-chift-client-requestid header on every POST. If a network timeout or retry causes the same request to be sent twice, Chift returns REQUEST_ALREADY_PROCESSED instead of creating a duplicate.See Idempotency for the full mechanism, and use Transaction Monitoring to check the outcome of a request whose response you never received (e.g. after a client-side timeout).Read the created_entity_id back
A successful POST returns the created resource. For long-running or asynchronous operations, the transaction monitoring endpoint also exposes
created_entity_id, so you don’t need a separate lookup to find what was created.Expect connector-specific rejections
The same payload can be valid for one target system and invalid for another (e.g. a required tax field, an account that must pre-exist). Treat validation errors as expected, not exceptional, and surface
error_code + detail to your own users rather than a generic failure.Updating resources (PATCH)
Send only the fields you're changing
PATCH bodies are partial by design — every field is optional. Only include the fields you actually want to modify; omitted fields are left untouched on the target system.Do not re-send a full resource read back from a GET as your PATCH body. If the resource has fields you didn’t set yourself (defaults, computed values, connector-specific extras), re-submitting them can overwrite state you didn’t intend to touch.
Don't use PATCH for read-modify-write increments
If a field represents a running total or counter, fetch the current value and PATCH the new absolute value — don’t assume the API will “add” to it. PATCH sets fields; it doesn’t apply deltas.