*REST API › Errors*

# `conflict`

> 409. The current state of the resource prevents the operation, a request with the same `Idempotency-Key` is still in flight, or another write held the resource, or the database aborted the transaction on a transient conflict, so nothing was written. The cause is in `errors[0].code`: `invalid_state` for the first, `in_progress` for the second and `lock_timeout` for the third. `detail` is not for deciding. HTTP 409.

HTTP status: `409` · Problem type: `https://docs.filmo.io/errors/conflict`

## When it happens

409. The current state of the resource prevents the operation, a request with the same `Idempotency-Key` is still in flight, or another write held the resource, or the database aborted the transaction on a transient conflict, so nothing was written. The cause is in `errors[0].code`: `invalid_state` for the first, `in_progress` for the second and `lock_timeout` for the third. `detail` is not for deciding.

## What to do

Branch on `errors[0].code`. For `in_progress` and `lock_timeout`, wait and send the same request again with the same `Idempotency-Key`; with backoff for `lock_timeout`. If an `in_progress` 409 persists for about two minutes, the reservation is treated as abandoned and the next attempt with the same key runs, so read the resource before retrying. For `invalid_state`, do not retry unchanged: read the resource and, if the request still fits, you may send it again; otherwise change it to fit its state; examples are archiving an order that is neither a draft nor cancelled, unreserving a cancelled order, or cancelling one already checked in.

## Retry

| Condition | What to do | Note |
| --- | --- | --- |
| 409 conflict · in_progress · Idempotency-Key: Yes | Retry with the same key | `errors[0].code` is `in_progress`: another request with the same `Idempotency-Key` is still running. Wait and retry with the same key (exponential backoff, up to 3 times): you get its stored response when it finishes. If the 409 persists for about two minutes, the reservation is treated as abandoned and the next attempt with the same key runs; read the resource before retrying. |
| 409 conflict · lock_timeout | Retry with backoff | `errors[0].code` is `lock_timeout`: another write held the resource, or the database aborted the transaction on a transient conflict; nothing was written. Retry with the same key and an exponential backoff, up to 3 times; if it persists, read the resource again. |
| 409 conflict · invalid_state | Read the resource first | `errors[0].code` is `invalid_state`: the state of the resource forbids the operation (a unique violation, a line of an atomic batch, an item deleted while saving). Do not retry unchanged: waiting never fixes it. Read the resource again; if the request still fits, you may send it again. |

## Fields of errors[]

| Name | Type | Description |
| --- | --- | --- |
| `errors[].code` | string | Stable code of the field error (`required`, `must_not_be_null`, `invalid_type`, `invalid_value`, `too_small`, `too_big`, `unknown_field`, `invalid_format`, `not_found`, `must_be_after`…). On a 409 `conflict` it says the cause: `in_progress` (another request with the same `Idempotency-Key` is still running), `lock_timeout` (another conditional write held the resource for more than five seconds) or `invalid_state` (the state of the resource forbids the operation). |

## Example

*conflict*

```json
{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}
```

## Returned by

- [`POST /api/v1/contacts`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/create-a-contact) — Create a contact
- [`PATCH /api/v1/contacts/{contactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/update-a-contact) — Update a contact
- [`DELETE /api/v1/contacts/{contactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/delete-a-contact) — Delete a contact
- [`PATCH /api/v1/contacts/{contactId}/preferences`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/update-the-commercial-terms-of-a-contact) — Update the commercial terms of a contact
- [`POST /api/v1/contacts/{contactId}/addresses`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/add-an-address-to-a-contact) — Add an address to a contact
- [`PATCH /api/v1/contacts/{contactId}/addresses/{addressId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/update-an-address-of-a-contact) — Update an address of a contact
- [`DELETE /api/v1/contacts/{contactId}/addresses/{addressId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/remove-an-address-from-a-contact) — Remove an address from a contact
- [`POST /api/v1/contacts/{contactId}/related-contacts`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/relate-two-contacts) — Relate two contacts
- [`PATCH /api/v1/contacts/{contactId}/related-contacts/{relatedContactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/change-the-role-of-a-relationship) — Change the role of a relationship
- [`DELETE /api/v1/contacts/{contactId}/related-contacts/{relatedContactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/unrelate-two-contacts) — Unrelate two contacts
- [`POST /api/v1/items`](https://docs.filmo.io/rest-api/endpoint-reference/items/create-an-item) — Create an item
- [`PATCH /api/v1/items/{itemId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-an-item) — Update an item
- [`DELETE /api/v1/items/{itemId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/delete-an-item) — Delete an item
- [`PATCH /api/v1/items/{itemId}/physical-properties`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-weight-and-dimensions) — Update weight and dimensions
- [`PATCH /api/v1/items/{itemId}/pricing`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-the-pricing-of-an-item) — Update the pricing of an item
- [`POST /api/v1/availability/check`](https://docs.filmo.io/rest-api/endpoint-reference/availability/check-item-availability) — Check item availability
- [`POST /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/create-an-order) — Create an order
- [`PATCH /api/v1/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/orders/update-the-header-of-an-order) — Update the header of an order
- [`POST /api/v1/projects`](https://docs.filmo.io/rest-api/endpoint-reference/projects/create-a-project) — Create a project
- [`PUT /api/v1/projects/{projectId}/archive`](https://docs.filmo.io/rest-api/endpoint-reference/projects/archive-or-restore-a-project) — Archive or restore a project
- [`PATCH /api/v1/projects/{projectId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/update-a-project) — Update a project
- [`PATCH /api/v1/serialized-items/{serializedItemId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-a-serialized-item) — Update a serialized item
- [`PATCH /api/v1/spaces/{spaceId}`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/update-a-warehouse-or-space) — Update a warehouse or space
- [`DELETE /api/v1/spaces/{spaceId}`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/delete-a-space) — Delete a space
- [`PUT /api/v1/spaces/{spaceId}/amenities`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/replace-the-amenities-and-equipment) — Replace the amenities and equipment
- [`PATCH /api/v1/spaces/{spaceId}/pricing`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/update-the-pricing-of-a-space) — Update the pricing of a space
- [`POST /api/v1/repair-tickets`](https://docs.filmo.io/rest-api/endpoint-reference/repair-tickets/create-a-repair-ticket) — Create a repair ticket
- [`PATCH /api/v1/repair-tickets/{ticketId}`](https://docs.filmo.io/rest-api/endpoint-reference/repair-tickets/update-a-repair-ticket) — Update a repair ticket
- [`POST /api/v1/vehicles`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/create-a-vehicle) — Create a vehicle
- [`PATCH /api/v1/vehicles/{vehicleId}`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/update-a-vehicle) — Update a vehicle
- [`DELETE /api/v1/vehicles/{vehicleId}`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/delete-a-vehicle) — Delete a vehicle
- [`POST /api/v1/staff`](https://docs.filmo.io/rest-api/endpoint-reference/staff/create-a-staff-member) — Create a staff member
- [`PATCH /api/v1/staff/{staffId}`](https://docs.filmo.io/rest-api/endpoint-reference/staff/update-a-staff-member) — Update a staff member
- [`DELETE /api/v1/staff/{staffId}`](https://docs.filmo.io/rest-api/endpoint-reference/staff/delete-a-staff-member) — Delete a staff member
- [`PATCH /api/v1/subrents/{subrentId}`](https://docs.filmo.io/rest-api/endpoint-reference/subrents/update-a-subrent) — Update a subrent
- [`PATCH /api/v1/purchase-orders/{purchaseOrderId}`](https://docs.filmo.io/rest-api/endpoint-reference/purchase-orders/update-a-purchase-order) — Update a purchase order
- [`POST /api/v1/staff/availability`](https://docs.filmo.io/rest-api/endpoint-reference/staff/check-staff-availability) — Check staff availability
- [`POST /api/v1/vehicles/availability`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/check-fleet-availability) — Check fleet availability
- [`POST /api/v1/tags`](https://docs.filmo.io/rest-api/endpoint-reference/tags/create-a-tag) — Create a tag
- [`DELETE /api/v1/tags/{tagId}`](https://docs.filmo.io/rest-api/endpoint-reference/tags/delete-a-tag) — Delete a tag
- [`POST /api/v1/tags/{tagId}/assignments`](https://docs.filmo.io/rest-api/endpoint-reference/tags/assign-a-tag-to-an-entity) — Assign a tag to an entity
- [`DELETE /api/v1/tags/{tagId}/assignments`](https://docs.filmo.io/rest-api/endpoint-reference/tags/remove-a-tag-from-an-entity) — Remove a tag from an entity
- [`POST /api/v1/kits`](https://docs.filmo.io/rest-api/endpoint-reference/kits/create-a-kit) — Create a kit
- [`PATCH /api/v1/kits/{kitId}`](https://docs.filmo.io/rest-api/endpoint-reference/kits/update-a-kit) — Update a kit
- [`POST /api/v1/collections`](https://docs.filmo.io/rest-api/endpoint-reference/collections/create-a-collection) — Create a collection
- [`PATCH /api/v1/collections/{collectionId}`](https://docs.filmo.io/rest-api/endpoint-reference/collections/update-a-collection) — Update a collection
- [`POST /api/v1/services`](https://docs.filmo.io/rest-api/endpoint-reference/services/create-a-service) — Create a service
- [`PATCH /api/v1/services/{serviceId}`](https://docs.filmo.io/rest-api/endpoint-reference/services/update-a-service) — Update a service
- [`POST /api/v1/internal-services`](https://docs.filmo.io/rest-api/endpoint-reference/internal-services/create-an-internal-service) — Create an internal service
- [`PATCH /api/v1/internal-services/{internalServiceId}`](https://docs.filmo.io/rest-api/endpoint-reference/internal-services/update-an-internal-service) — Update an internal service
- [`POST /api/v1/planner/assignments`](https://docs.filmo.io/rest-api/endpoint-reference/planner/assign-a-resource-to-a-service) — Assign a resource to a service
- [`POST /api/v1/planner/assignments/remove`](https://docs.filmo.io/rest-api/endpoint-reference/planner/remove-a-resource-from-a-service) — Remove a resource from a service
- [`POST /api/v1/availability/unavailabilities`](https://docs.filmo.io/rest-api/endpoint-reference/availability/declare-an-unavailability) — Declare an unavailability
- [`PATCH /api/v1/availability/unavailabilities/{unavailabilityId}`](https://docs.filmo.io/rest-api/endpoint-reference/availability/correct-or-close-an-unavailability) — Correct or close an unavailability
- [`DELETE /api/v1/availability/unavailabilities/{unavailabilityId}`](https://docs.filmo.io/rest-api/endpoint-reference/availability/delete-an-unavailability) — Delete an unavailability
- [`POST /api/v1/incidents`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/open-an-incident) — Open an incident
- [`PATCH /api/v1/incidents/{incidentId}`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/update-an-incident) — Update an incident
- [`POST /api/v1/incidents/{incidentId}/comments`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/comment-on-an-incident) — Comment on an incident
- [`POST /api/v1/notes`](https://docs.filmo.io/rest-api/endpoint-reference/notes/write-a-note-on-an-entity) — Write a note on an entity
- [`POST /api/v1/tasks`](https://docs.filmo.io/rest-api/endpoint-reference/tasks/create-a-task) — Create a task
- [`PATCH /api/v1/tasks/{taskId}`](https://docs.filmo.io/rest-api/endpoint-reference/tasks/update-a-task) — Update a task
- [`DELETE /api/v1/tasks/{taskId}`](https://docs.filmo.io/rest-api/endpoint-reference/tasks/delete-a-task) — Delete a task
- [`POST /api/v1/crm/opportunities`](https://docs.filmo.io/rest-api/endpoint-reference/crm/create-an-opportunity) — Create an opportunity
- [`PATCH /api/v1/crm/opportunities/{opportunityId}`](https://docs.filmo.io/rest-api/endpoint-reference/crm/update-an-opportunity) — Update an opportunity
- [`PATCH /api/v1/crm/opportunities/{opportunityId}/stage`](https://docs.filmo.io/rest-api/endpoint-reference/crm/move-an-opportunity-to-another-stage) — Move an opportunity to another stage
- [`POST /api/v1/crm/opportunities/{opportunityId}/close`](https://docs.filmo.io/rest-api/endpoint-reference/crm/close-an-opportunity) — Close an opportunity
- [`POST /api/v1/crm/opportunities/{opportunityId}/links`](https://docs.filmo.io/rest-api/endpoint-reference/crm/link-a-document-to-an-opportunity) — Link a document to an opportunity
- [`POST /api/v1/purchase-orders/{purchaseOrderId}/approve`](https://docs.filmo.io/rest-api/endpoint-reference/purchase-orders/approve-a-purchase-order) — Approve a purchase order
- [`POST /api/v1/purchase-orders/{purchaseOrderId}/receive`](https://docs.filmo.io/rest-api/endpoint-reference/purchase-orders/receive-material-from-a-purchase-order) — Receive material from a purchase order
- [`POST /api/v1/treasury/payments`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/record-an-incoming-or-outgoing-payment) — Record an incoming or outgoing payment
- [`PATCH /api/v1/treasury/payments/{paymentId}`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/update-a-payment) — Update a payment
- [`POST /api/v1/treasury/payments/{paymentId}/links`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/link-a-payment-to-a-document) — Link a payment to a document
- [`POST /api/v1/orders/{orderId}/cancel`](https://docs.filmo.io/rest-api/endpoint-reference/orders/cancel-an-order) — Cancel an order
- [`PUT /api/v1/orders/{orderId}/archive`](https://docs.filmo.io/rest-api/endpoint-reference/orders/archive-or-restore-an-order) — Archive or restore an order
- [`PUT /api/v1/items/{itemId}/accessories`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-the-accessories-of-an-item) — Update the accessories of an item
- [`PUT /api/v1/items/{itemId}/alternatives`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-the-alternatives-of-an-item) — Update the alternatives of an item
- [`PATCH /api/v1/items/{itemId}/variants/{variantId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-a-variant-of-an-item) — Update a variant of an item
- [`POST /api/v1/contacts/lookup`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/look-up-contacts-by-external-reference) — Look up contacts by external reference
- [`POST /api/v1/orders/line-items/returns`](https://docs.filmo.io/rest-api/endpoint-reference/orders/return-order-lines) — Return order lines
- [`POST /api/v1/ai/ask`](https://docs.filmo.io/rest-api/endpoint-reference/ai/ask-the-ai-about-your-data) — Ask the AI about your data
- [`POST /api/v1/workflows/{workflowId}/runs`](https://docs.filmo.io/rest-api/endpoint-reference/workflows/run-a-workflow) — Run a workflow
- [`POST /api/v1/orders/{orderId}/reserve`](https://docs.filmo.io/rest-api/endpoint-reference/orders/reserve-an-order) — Reserve an order
- [`POST /api/v1/orders/{orderId}/unreserve`](https://docs.filmo.io/rest-api/endpoint-reference/orders/unreserve-an-order) — Unreserve an order
- [`POST /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/link-an-order-to-a-project) — Link an order to a project
- [`DELETE /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/unlink-an-order-from-a-project) — Unlink an order from a project
- [`POST /api/v1/invoices/{invoiceId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/validate-an-invoice) — Validate an invoice
- [`POST /api/v1/invoices/{invoiceId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/void-an-invoice) — Void an invoice
- [`PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/create-or-update-the-mirror-of-an-externally-issued-invoice) — Create or update the mirror of an externally issued invoice
- [`POST /api/v1/credit-notes/{creditNoteId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/credit-notes/validate-a-credit-note) — Validate a credit note
- [`POST /api/v1/credit-notes/{creditNoteId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/credit-notes/void-a-credit-note) — Void a credit note
- [`PATCH /api/v1/proformas/{proformaId}/status`](https://docs.filmo.io/rest-api/endpoint-reference/proformas/change-the-commercial-status-of-a-proforma) — Change the commercial status of a proforma
- [`PATCH /api/v1/quotes/{quoteId}/status`](https://docs.filmo.io/rest-api/endpoint-reference/quotes/change-the-commercial-status-of-a-quote) — Change the commercial status of a quote
- [`POST /api/v1/contracts/{contractId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/validate-a-contract) — Validate a contract
- [`POST /api/v1/contracts/{contractId}/sign`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/record-the-signature-of-a-contract) — Record the signature of a contract
- [`POST /api/v1/contracts/{contractId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/void-a-contract) — Void a contract
- [`POST /api/v1/contracts/{contractId}/cancel`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/cancel-a-contract-operatively) — Cancel a contract operatively
- [`POST /api/v1/supplier-invoices/{supplierInvoiceId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/supplier-invoices/validate-a-supplier-invoice) — Validate a supplier invoice
- [`POST /api/v1/supplier-invoices/{supplierInvoiceId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/supplier-invoices/void-a-supplier-invoice) — Void a supplier invoice

## Through MCP

A tool call that fails comes back with `isError` set and the problem as structured content, with the same `code`.

---

Canonical URL: https://docs.filmo.io/rest-api/errors/conflict  
Last updated: 2026-10-25