412

API problem detail

Precondition Failed

Description

This problem happens when the If-Match ETag you sent no longer matches the current document. It applies to every write that accepts If-Match: the permission replacement PUT /User/{userId}/Permissions, the branch bank-account replacement PUT /Branch/{branchId}/BankAccounts, and the PUT and DELETE operations on addresses, bank accounts, branches, disbursements, pay ins, pay outs, phone numbers, target accounts, and users when you send an If-Match header. The document changed after you read it.

What a 412 means after a lost response depends on the endpoint:

  • PUT /User/{userId}/Permissions checks the idempotency key first. A same-key retry of a change that was applied replays the original 200, so a 412 here means your change was not applied and someone else changed the document.
  • Every other If-Match write compares the ETag before the request is processed. A same-key retry after your own first attempt succeeded also returns 412, because that attempt changed the ETag. Here a 412 does not tell you who changed it.

Response errorCode: PRECONDITION_FAILED.

Experience API error bodies also carry errorCode, resolution, and traceId. Branch on errorCode, not on title or detail; see fields on every error.

How to resolve

Re-read the document with GET and compare it with what you intended to write. If your change is already there, stop. If it is missing, re-apply it on top of the current document with the fresh ETag in If-Match and a new X-Idempotency-Key. Do not blind-retry the original request.
Back to all problem details