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

{
  "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"
    }
  ]
}

When it happens

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

Retry with the same key409 conflict · in_progress · Idempotency-Key: Yes
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.
Retry with backoff409 conflict · lock_timeout
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.
Read the resource first409 conflict · invalid_state
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[]

errors[].codestring

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).

Returned by

98 operations

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

Was this page helpful?

Example