Precondition Failed

← Back to Overview

This error occurs when you attempt to update or delete a record, but the record was modified after you fetched it. In HTTP APIs, this is called an Optimistic Concurrency Collision or a Precondition Failure.

It acts as an automated safety shield to prevent “lost updates” — ensuring that one user’s changes do not silently overwrite another user’s simultaneous edits.

---

Error Response Example (RFC 9457)

{
  "type": "https://docs.apinow.app/errors/precondition-failed",
  "title": "Precondition Failed",
  "status": 412,
  "code": "E_PRECONDITION_FAILED",
  "detail": "If-Match precondition failed. Current ETag '\"2\"' does not match '\"1\"'.",
  "hint": "Retrieve the latest version of the resource (GET /orders/101) before attempting this mutation.",
  "instance": "/orders/101"
}

---

What Caused This Error?

1. Stale Revision (If-Match): Your request included an If-Match header containing a revision tag (ETag) from an older version of the record. Since you last read the record, another user, background job, or API call saved a new change.
2. Date Out of Sync (If-Unmodified-Since): Your request included an If-Unmodified-Since header, but the record’s modification date is newer than the date you specified.
3. Missing Resource: You passed If-Match: * (indicating the resource must exist), but the target record was not found.

---

Troubleshooting Guide

For API Consumers (Frontends & No-Code Apps)

• Fetch the Newest Data: Call GET /resource/:id to retrieve the current state of the record and its latest ETag header.
• Review or Merge Changes: Inspect the newest record or display a message to the user informing them that the record has changed.
• Retry the Save: Submit your PUT, PATCH, or DELETE request again, supplying the updated ETag value in the If-Match header.

Handling 412 in Bubble, FlutterFlow, or Web Apps

When loading a record into a form, store the ETag from the response headers in page state or a local variable. When the user submits their updates, pass that saved ETag in the If-Match header. If you receive a 412, display a friendly prompt: “This record was updated while you had it open. Please refresh to see the latest changes.”

For API Authors (API & Domain Modeler Notes)

• Automatic Revision Tracking: API Now automatically maintains revision tokens (_etag) on all database tables for single-resource operations (Update and Delete).
• Version Semantics: If your entity has a property tagged with the Version semantic module, API Now evaluates If-Match against clean sequential integers ("1", "2", "3") instead of internal hex tokens.
• 1:1 Connected Records: Modifying a 1:1 sub-resource (e.g. PUT /users/:id/profile) automatically updates the parent entity’s ETag to prevent stale reads on the parent resource.