*API REST › Errores*

# `conflict`

> 409. El estado actual del recurso impide la operación, una petición con la misma `Idempotency-Key` sigue en curso, u otra escritura retenía el recurso, o la base de datos abortó la transacción por un conflicto transitorio, así que no se escribió nada. La causa está en `errors[0].code`: `invalid_state` para el primer caso, `in_progress` para el segundo y `lock_timeout` para el tercero. `detail` no sirve para decidir. HTTP 409.

Estado HTTP: `409` · Tipo del problema: `https://docs.filmo.io/errors/conflict`

## Cuándo ocurre

409. El estado actual del recurso impide la operación, una petición con la misma `Idempotency-Key` sigue en curso, u otra escritura retenía el recurso, o la base de datos abortó la transacción por un conflicto transitorio, así que no se escribió nada. La causa está en `errors[0].code`: `invalid_state` para el primer caso, `in_progress` para el segundo y `lock_timeout` para el tercero. `detail` no sirve para decidir.

## Qué hacer

Ramifica según `errors[0].code`. Para `in_progress` y `lock_timeout`, espera y envía de nuevo la misma petición con la misma `Idempotency-Key`; con backoff para `lock_timeout`. Si un 409 `in_progress` persiste unos dos minutos, la reserva se considera abandonada y el siguiente intento con la misma clave se ejecuta, así que lee el recurso antes de reintentar. Para `invalid_state`, no reintentes sin cambios: lee el recurso y, si la petición aún encaja, puedes enviarla de nuevo; si no, cámbiala para que encaje con su estado; por ejemplo, archivar un pedido que no es borrador ni está cancelado, anular la reserva de un pedido cancelado o cancelar uno ya recepcionado.

## Reintento

| Condición | Qué hacer | Nota |
| --- | --- | --- |
| 409 conflict · in_progress · Idempotency-Key: Sí | Reintentar con la misma clave | `errors[0].code` es `in_progress`: otra petición con la misma `Idempotency-Key` sigue en curso. Espera y reintenta con la misma clave (espera exponencial, hasta 3 veces): recibirás su respuesta guardada cuando termine. |
| 409 conflict · lock_timeout | Reintentar con espera exponencial | `errors[0].code` es `lock_timeout`: otra escritura condicional retuvo el recurso más de 5 s. Reintenta con la misma clave y espera exponencial, hasta 3 veces; si persiste, vuelve a leer el recurso. |
| 409 conflict · invalid_state | Leer antes el recurso | `errors[0].code` es `invalid_state`: el estado del recurso impide la operación (una violación de unicidad, una línea de un lote atómico). No reintentes: esperar no lo arregla nunca. Vuelve a leer el recurso y decide según su estado actual. |

## Campos de errors[]

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `errors[].code` | string | Código estable del error de campo (`required`, `must_not_be_null`, `invalid_type`, `invalid_value`, `too_small`, `too_big`, `unknown_field`, `invalid_format`, `not_found`, `must_be_after`…). En un 409 `conflict` indica la causa: `in_progress` (otra petición con la misma `Idempotency-Key` sigue en curso), `lock_timeout` (otra escritura condicional retuvo el recurso durante más de cinco segundos) o `invalid_state` (el estado del recurso prohíbe la operación). |

## Ejemplo

*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"
    }
  ]
}
```

## Lo devuelven

- [`POST /api/v1/contacts`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/create-a-contact) — Crear un contacto
- [`PATCH /api/v1/contacts/{contactId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/update-a-contact) — Actualizar un contacto
- [`DELETE /api/v1/contacts/{contactId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/delete-a-contact) — Eliminar un contacto
- [`PATCH /api/v1/contacts/{contactId}/preferences`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/update-the-commercial-terms-of-a-contact) — Actualizar las condiciones comerciales de un contacto
- [`POST /api/v1/contacts/{contactId}/addresses`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/add-an-address-to-a-contact) — Añadir una dirección a un contacto
- [`PATCH /api/v1/contacts/{contactId}/addresses/{addressId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/update-an-address-of-a-contact) — Actualizar una dirección de un contacto
- [`DELETE /api/v1/contacts/{contactId}/addresses/{addressId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/remove-an-address-from-a-contact) — Quitar una dirección de un contacto
- [`POST /api/v1/contacts/{contactId}/related-contacts`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/relate-two-contacts) — Relacionar dos contactos
- [`PATCH /api/v1/contacts/{contactId}/related-contacts/{relatedContactId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/change-the-role-of-a-relationship) — Cambiar el rol de una relación
- [`DELETE /api/v1/contacts/{contactId}/related-contacts/{relatedContactId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/unrelate-two-contacts) — Quitar la relación entre dos contactos
- [`POST /api/v1/items`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/create-an-item) — Crear un artículo
- [`PATCH /api/v1/items/{itemId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/update-an-item) — Actualizar un artículo
- [`DELETE /api/v1/items/{itemId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/delete-an-item) — Eliminar un artículo
- [`PATCH /api/v1/items/{itemId}/physical-properties`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/update-weight-and-dimensions) — Actualizar peso y dimensiones
- [`PATCH /api/v1/items/{itemId}/pricing`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/update-the-pricing-of-an-item) — Actualizar los precios de un artículo
- [`POST /api/v1/availability/check`](https://docs.filmo.io/es/rest-api/endpoint-reference/availability/check-item-availability) — Comprobar la disponibilidad de artículos
- [`POST /api/v1/orders`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/create-an-order) — Crear un pedido
- [`PATCH /api/v1/orders/{orderId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/update-the-header-of-an-order) — Actualizar la cabecera de un pedido
- [`POST /api/v1/projects`](https://docs.filmo.io/es/rest-api/endpoint-reference/projects/create-a-project) — Crear un proyecto
- [`PUT /api/v1/projects/{projectId}/archive`](https://docs.filmo.io/es/rest-api/endpoint-reference/projects/archive-or-restore-a-project) — Archivar o restaurar un proyecto
- [`PATCH /api/v1/projects/{projectId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/projects/update-a-project) — Actualizar un proyecto
- [`PATCH /api/v1/serialized-items/{serializedItemId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/update-a-serialized-item) — Actualizar una unidad serializada
- [`PATCH /api/v1/spaces/{spaceId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/spaces/update-a-warehouse-or-space) — Actualizar un almacén o espacio
- [`DELETE /api/v1/spaces/{spaceId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/spaces/delete-a-space) — Eliminar un espacio
- [`PUT /api/v1/spaces/{spaceId}/amenities`](https://docs.filmo.io/es/rest-api/endpoint-reference/spaces/replace-the-amenities-and-equipment) — Reemplazar las comodidades y el equipamiento
- [`PATCH /api/v1/spaces/{spaceId}/pricing`](https://docs.filmo.io/es/rest-api/endpoint-reference/spaces/update-the-pricing-of-a-space) — Actualizar los precios de un espacio
- [`POST /api/v1/repair-tickets`](https://docs.filmo.io/es/rest-api/endpoint-reference/repair-tickets/create-a-repair-ticket) — Crear un parte de reparación
- [`PATCH /api/v1/repair-tickets/{ticketId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/repair-tickets/update-a-repair-ticket) — Actualizar un ticket de reparación
- [`POST /api/v1/vehicles`](https://docs.filmo.io/es/rest-api/endpoint-reference/vehicles/create-a-vehicle) — Crear un vehículo
- [`PATCH /api/v1/vehicles/{vehicleId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/vehicles/update-a-vehicle) — Actualizar un vehículo
- [`DELETE /api/v1/vehicles/{vehicleId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/vehicles/delete-a-vehicle) — Eliminar un vehículo
- [`POST /api/v1/staff`](https://docs.filmo.io/es/rest-api/endpoint-reference/staff/create-a-staff-member) — Crear un miembro del personal
- [`PATCH /api/v1/staff/{staffId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/staff/update-a-staff-member) — Actualizar un miembro del personal
- [`DELETE /api/v1/staff/{staffId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/staff/delete-a-staff-member) — Eliminar un miembro del personal
- [`PATCH /api/v1/subrents/{subrentId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/subrents/update-a-subrent) — Actualizar un subalquiler
- [`PATCH /api/v1/purchase-orders/{purchaseOrderId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/purchase-orders/update-a-purchase-order) — Actualizar una orden de compra
- [`POST /api/v1/staff/availability`](https://docs.filmo.io/es/rest-api/endpoint-reference/staff/check-staff-availability) — Comprobar la disponibilidad del personal
- [`POST /api/v1/vehicles/availability`](https://docs.filmo.io/es/rest-api/endpoint-reference/vehicles/check-fleet-availability) — Comprobar la disponibilidad de la flota
- [`POST /api/v1/tags`](https://docs.filmo.io/es/rest-api/endpoint-reference/tags/create-a-tag) — Crear una etiqueta
- [`DELETE /api/v1/tags/{tagId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/tags/delete-a-tag) — Eliminar una etiqueta
- [`POST /api/v1/tags/{tagId}/assignments`](https://docs.filmo.io/es/rest-api/endpoint-reference/tags/assign-a-tag-to-an-entity) — Asignar una etiqueta a una entidad
- [`DELETE /api/v1/tags/{tagId}/assignments`](https://docs.filmo.io/es/rest-api/endpoint-reference/tags/remove-a-tag-from-an-entity) — Quitar una etiqueta de una entidad
- [`POST /api/v1/kits`](https://docs.filmo.io/es/rest-api/endpoint-reference/kits/create-a-kit) — Crear un kit
- [`PATCH /api/v1/kits/{kitId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/kits/update-a-kit) — Actualizar un kit
- [`POST /api/v1/collections`](https://docs.filmo.io/es/rest-api/endpoint-reference/collections/create-a-collection) — Crear una colección
- [`PATCH /api/v1/collections/{collectionId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/collections/update-a-collection) — Actualizar una colección
- [`POST /api/v1/services`](https://docs.filmo.io/es/rest-api/endpoint-reference/services/create-a-service) — Crear un servicio
- [`PATCH /api/v1/services/{serviceId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/services/update-a-service) — Actualizar un servicio
- [`POST /api/v1/internal-services`](https://docs.filmo.io/es/rest-api/endpoint-reference/internal-services/create-an-internal-service) — Crear un servicio interno
- [`PATCH /api/v1/internal-services/{internalServiceId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/internal-services/update-an-internal-service) — Actualizar un servicio interno
- [`POST /api/v1/planner/assignments`](https://docs.filmo.io/es/rest-api/endpoint-reference/planner/assign-a-resource-to-a-service) — Asignar un recurso a un servicio
- [`POST /api/v1/planner/assignments/remove`](https://docs.filmo.io/es/rest-api/endpoint-reference/planner/remove-a-resource-from-a-service) — Quitar un recurso de un servicio
- [`POST /api/v1/availability/unavailabilities`](https://docs.filmo.io/es/rest-api/endpoint-reference/availability/declare-an-unavailability) — Declarar una indisponibilidad
- [`PATCH /api/v1/availability/unavailabilities/{unavailabilityId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/availability/correct-or-close-an-unavailability) — Corregir o cerrar una indisponibilidad
- [`DELETE /api/v1/availability/unavailabilities/{unavailabilityId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/availability/delete-an-unavailability) — Eliminar una indisponibilidad
- [`POST /api/v1/incidents`](https://docs.filmo.io/es/rest-api/endpoint-reference/incidents/open-an-incident) — Abrir una incidencia
- [`PATCH /api/v1/incidents/{incidentId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/incidents/update-an-incident) — Actualizar una incidencia
- [`POST /api/v1/incidents/{incidentId}/comments`](https://docs.filmo.io/es/rest-api/endpoint-reference/incidents/comment-on-an-incident) — Comentar una incidencia
- [`POST /api/v1/notes`](https://docs.filmo.io/es/rest-api/endpoint-reference/notes/write-a-note-on-an-entity) — Escribe una nota en una entidad
- [`POST /api/v1/tasks`](https://docs.filmo.io/es/rest-api/endpoint-reference/tasks/create-a-task) — Crear una tarea
- [`PATCH /api/v1/tasks/{taskId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/tasks/update-a-task) — Actualizar una tarea
- [`DELETE /api/v1/tasks/{taskId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/tasks/delete-a-task) — Eliminar una tarea
- [`POST /api/v1/crm/opportunities`](https://docs.filmo.io/es/rest-api/endpoint-reference/crm/create-an-opportunity) — Crear una oportunidad
- [`PATCH /api/v1/crm/opportunities/{opportunityId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/crm/update-an-opportunity) — Actualizar una oportunidad
- [`PATCH /api/v1/crm/opportunities/{opportunityId}/stage`](https://docs.filmo.io/es/rest-api/endpoint-reference/crm/move-an-opportunity-to-another-stage) — Mover una oportunidad a otra etapa
- [`POST /api/v1/crm/opportunities/{opportunityId}/close`](https://docs.filmo.io/es/rest-api/endpoint-reference/crm/close-an-opportunity) — Cerrar una oportunidad
- [`POST /api/v1/crm/opportunities/{opportunityId}/links`](https://docs.filmo.io/es/rest-api/endpoint-reference/crm/link-a-document-to-an-opportunity) — Vincular un documento a una oportunidad
- [`POST /api/v1/purchase-orders/{purchaseOrderId}/approve`](https://docs.filmo.io/es/rest-api/endpoint-reference/purchase-orders/approve-a-purchase-order) — Aprobar un pedido de compra
- [`POST /api/v1/purchase-orders/{purchaseOrderId}/receive`](https://docs.filmo.io/es/rest-api/endpoint-reference/purchase-orders/receive-material-from-a-purchase-order) — Recibir material de un pedido de compra
- [`POST /api/v1/treasury/payments`](https://docs.filmo.io/es/rest-api/endpoint-reference/treasury/record-an-incoming-or-outgoing-payment) — Registrar un pago entrante o saliente
- [`PATCH /api/v1/treasury/payments/{paymentId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/treasury/update-a-payment) — Actualizar un pago
- [`POST /api/v1/treasury/payments/{paymentId}/links`](https://docs.filmo.io/es/rest-api/endpoint-reference/treasury/link-a-payment-to-a-document) — Vincular un pago a un documento
- [`POST /api/v1/orders/{orderId}/cancel`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/cancel-an-order) — Cancelar un pedido
- [`PUT /api/v1/orders/{orderId}/archive`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/archive-or-restore-an-order) — Archivar o restaurar un pedido
- [`PUT /api/v1/items/{itemId}/accessories`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/update-the-accessories-of-an-item) — Actualizar los accesorios de un artículo
- [`PUT /api/v1/items/{itemId}/alternatives`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/update-the-alternatives-of-an-item) — Actualizar las alternativas de un artículo
- [`PATCH /api/v1/items/{itemId}/variants/{variantId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/update-a-variant-of-an-item) — Actualizar una variante de un artículo
- [`POST /api/v1/contacts/lookup`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/look-up-contacts-by-external-reference) — Buscar contactos por referencia externa
- [`POST /api/v1/orders/line-items/returns`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/return-order-lines) — Devolver líneas de pedido
- [`POST /api/v1/ai/ask`](https://docs.filmo.io/es/rest-api/endpoint-reference/ai/ask-the-ai-about-your-data) — Preguntar a la IA sobre tus datos
- [`POST /api/v1/workflows/{workflowId}/runs`](https://docs.filmo.io/es/rest-api/endpoint-reference/workflows/run-a-workflow) — Ejecutar un workflow
- [`POST /api/v1/orders/{orderId}/reserve`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/reserve-an-order) — Reservar un pedido
- [`POST /api/v1/orders/{orderId}/unreserve`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/unreserve-an-order) — Anula la reserva de un pedido
- [`POST /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/projects/link-an-order-to-a-project) — Vincular un pedido a un proyecto
- [`DELETE /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/projects/unlink-an-order-from-a-project) — Desvincular un pedido de un proyecto
- [`POST /api/v1/invoices/{invoiceId}/validate`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/validate-an-invoice) — Validar una factura
- [`POST /api/v1/invoices/{invoiceId}/void`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/void-an-invoice) — Anular una factura
- [`PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/create-or-update-the-mirror-of-an-externally-issued-invoice) — Crear o actualizar el espejo de una factura emitida externamente
- [`POST /api/v1/credit-notes/{creditNoteId}/validate`](https://docs.filmo.io/es/rest-api/endpoint-reference/credit-notes/validate-a-credit-note) — Validar una nota de crédito
- [`POST /api/v1/credit-notes/{creditNoteId}/void`](https://docs.filmo.io/es/rest-api/endpoint-reference/credit-notes/void-a-credit-note) — Anular una nota de crédito
- [`PATCH /api/v1/proformas/{proformaId}/status`](https://docs.filmo.io/es/rest-api/endpoint-reference/proformas/change-the-commercial-status-of-a-proforma) — Cambiar el estado comercial de una proforma
- [`PATCH /api/v1/quotes/{quoteId}/status`](https://docs.filmo.io/es/rest-api/endpoint-reference/quotes/change-the-commercial-status-of-a-quote) — Cambiar el estado comercial de un presupuesto
- [`POST /api/v1/contracts/{contractId}/validate`](https://docs.filmo.io/es/rest-api/endpoint-reference/contracts/validate-a-contract) — Validar un contrato
- [`POST /api/v1/contracts/{contractId}/sign`](https://docs.filmo.io/es/rest-api/endpoint-reference/contracts/record-the-signature-of-a-contract) — Registrar la firma de un contrato
- [`POST /api/v1/contracts/{contractId}/void`](https://docs.filmo.io/es/rest-api/endpoint-reference/contracts/void-a-contract) — Anular un contrato
- [`POST /api/v1/contracts/{contractId}/cancel`](https://docs.filmo.io/es/rest-api/endpoint-reference/contracts/cancel-a-contract-operatively) — Cancelar un contrato a efectos operativos
- [`POST /api/v1/supplier-invoices/{supplierInvoiceId}/validate`](https://docs.filmo.io/es/rest-api/endpoint-reference/supplier-invoices/validate-a-supplier-invoice) — Validar una factura de proveedor
- [`POST /api/v1/supplier-invoices/{supplierInvoiceId}/void`](https://docs.filmo.io/es/rest-api/endpoint-reference/supplier-invoices/void-a-supplier-invoice) — Anular una factura de proveedor

## Por MCP

Una llamada a una herramienta que falla vuelve con `isError` y el problema como contenido estructurado, con el mismo `code`.

---

URL canónica: https://docs.filmo.io/es/rest-api/errors/conflict  
Última actualización: 2026-10-25