*API REST › Guías*

# Respuestas

> Las respuestas correctas envuelven su contenido en `data`; las listas añaden `pagination`; algunas operaciones añaden `meta`; los errores son problemas RFC 9457. Las respuestas de la API comparten un mismo conjunto de cabeceras.

## Variantes del sobre

### Lista

Una lista devuelve sus registros en `data` y el estado de paginación en `pagination`. `nextCursor` es `null` en la última página. `total` aparece solo cuando lo pides con [`includeTotal`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/list-orders#param-includeTotal).

*GET /api/v1/orders?limit=1 (recortado a unos pocos campos)*

```json
{
  "data": [
    {
      "id": "5e8d1a9c",
      "orderNumber": "ORD-0412",
      "status": "reserved",
      "startDate": "2026-10-17T08:00:00.000Z",
      "endDate": "2026-10-19T17:00:00.000Z",
      "contact": { "id": "c71f40b2", "name": "Acme Rentals" },
      "grossPrice": "1234.50"
    }
  ],
  "pagination": { "nextCursor": "opaque-cursor", "hasMore": true }
}
```

### Recurso único

Una lectura de detalle, una creación y una actualización devuelven el recurso en `data`. Las operaciones que crean un recurso responden 201; las lecturas y las actualizaciones responden 200.

### Recurso con meta

Unas pocas operaciones también te informan, en `meta`, de lo que la llamada hizo en otros registros. [`POST /api/v1/orders/{orderId}/reserve`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/reserve-an-order) informa `meta.tasksCreated`, las tareas de entrega y devolución que creó la reserva; [`POST /api/v1/orders/{orderId}/cancel`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/cancel-an-order) informa `meta.tasksDeleted`. Ambas devuelven el pedido completo en `data`.

### Sin cuerpo

La mayoría de los borrados y las dos operaciones de archivado ([`PUT /api/v1/orders/{orderId}/archive`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/archive-or-restore-an-order) y [`PUT /api/v1/projects/{projectId}/archive`](https://docs.filmo.io/es/rest-api/endpoint-reference/projects/archive-or-restore-a-project)) responden 204 sin cuerpo. Cuatro borrados responden 200 y devuelven en su lugar el registro que han cambiado: [`DELETE /api/v1/contacts/{contactId}/addresses/{addressId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/remove-an-address-from-a-contact) y [`DELETE /api/v1/contacts/{contactId}/related-contacts/{relatedContactId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/contacts/unrelate-two-contacts) devuelven el contacto, [`DELETE /api/v1/tags/{tagId}/assignments`](https://docs.filmo.io/es/rest-api/endpoint-reference/tags/remove-a-tag-from-an-entity) devuelve el resultado de la desasignación y [`DELETE /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/projects/unlink-an-order-from-a-project) devuelve el proyecto. Una lectura condicional cuyo `ETag` está vigente responde 304, también sin cuerpo.

### Resultados del lote

[`POST /api/v1/orders/line-items/returns`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/return-order-lines) es un lote. Responde 200 con un resultado por elemento, en el orden de la petición. Con `atomic: false` responde 207 y cada elemento lleva su propio `status` y `error`. Consulta la tabla de reintentos en [Errores](https://docs.filmo.io/es/rest-api/guides/errors#retry).

### Errores

Los errores son `application/problem+json` y llevan `type`, `title`, `status`, `code`, `detail` y `requestId`, además de `errors`, `requiredScope`, `requiredAddon` o `retryAfter` cuando corresponden. Se describen en [Errores](https://docs.filmo.io/es/rest-api/guides/errors).

## Cabeceras de respuesta

Estas cabeceras provienen del documento OpenAPI, más la estándar `Date`.

| Cabecera | Dónde | Qué te dice |
| --- | --- | --- |
| `X-Request-Id` | Todas las respuestas de la API. No los endpoints de OAuth, ni el 401 del descubrimiento de MCP | El identificador de la petición (`req_…`), generado por el servidor. Los cuerpos de error lo repiten como `requestId`; el 401 del endpoint MCP lo lleva solo en el cuerpo. Regístralo y cítalo al contactar con soporte. |
| `RateLimit-Limit` | Toda respuesta que consumió cuota (todas salvo un 401 y un 403 `insufficient_scope`) | Peticiones permitidas por minuto en la cuota más estricta que consumió la petición. |
| `RateLimit-Remaining` | Igual | Peticiones restantes en la ventana actual de un minuto de esa cuota. |
| `RateLimit-Reset` | Igual | Segundos hasta que esa ventana se reinicia. |
| `Retry-After` | Respuestas 429 | Segundos que esperar antes de reintentar; el problema 429 repite el valor en `retryAfter`. Consulta Límites de peticiones. |
| `ETag` | Lecturas de detalle y escrituras que devuelven el recurso | Una etiqueta fuerte de la representación. Devuélvela como `If-Match` en una escritura, o como `If-None-Match` en una lectura. |
| `Content-Language` | Respuestas de error | El idioma de `detail` y `errors[].message`, negociado a partir de `Accept-Language`. |
| `Idempotent-Replay` | Declarado por las operaciones de escritura; presente en una respuesta reproducida para un `Idempotency-Key` repetido | `true` cuando es la respuesta almacenada del primer intento, no una ejecución nueva. Está ausente en la primera ejecución, y un error almacenado también se reproduce. |
| `Date` | Todas las respuestas | La hora de los servidores de Filmo. Úsala, y no tu propio reloj, siempre que calcules una ventana para lecturas incrementales. |
| `Deprecation`, `Sunset`, `Link` | Respuestas de una operación obsoleta | Anuncia que la operación está obsoleta, el día en que se retirará y dónde está el aviso (`rel="deprecation"`). |

Las cabeceras de cuota se explican en [Límites de peticiones](https://docs.filmo.io/es/rest-api/guides/rate-limits), `Idempotent-Replay` en [Idempotencia](https://docs.filmo.io/es/rest-api/guides/idempotency) y `ETag` en [Concurrencia](https://docs.filmo.io/es/rest-api/guides/concurrency).

## Lecturas condicionales

Las lecturas de detalle devuelven un `ETag`. Envía el que ya tienes en `If-None-Match`: si sigue vigente, la respuesta es 304 sin cuerpo y con la cabecera `ETag`, y tu copia está al día. Si el recurso cambió, recibes el 200 completo con un `ETag` nuevo.

```bash
# First read: note the ETag header.
curl -sS -D - -o /dev/null "https://app.filmo.io/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY"

# Later: ask only for a newer version (paste the ETag you received, quotes included).
curl -sS -i "https://app.filmo.io/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H 'If-None-Match: "<the ETag you received>"'
```

## Avisos en meta

Una operación marcada como obsoleta lleva las cabeceras `Deprecation` y `Sunset`, y cada cuerpo JSON que devuelve lleva `meta.warnings[]` con una entrada cuyo `code` es `deprecated`. Registra esos avisos y configura alertas sobre ellos: el día de la retirada es al menos seis meses posterior a la entrada en vigor de la obsolescencia. Más adelante pueden añadirse entradas con otros códigos; ignora las que no conozcas.

```json
{ "data": { "id": "5e8d1a9c" }, "meta": { "warnings": [{ "code": "deprecated" }] } }
```

## Estados en uso

| Estado | Significado |
| --- | --- |
| 200 | Éxito. Lecturas, actualizaciones, acciones y consultas. |
| 201 | Se creó un recurso. |
| 204 | Éxito sin cuerpo: la mayoría de los borrados y las operaciones de archivado. Cuatro borrados responden 200 con el registro modificado. |
| 207 | Resultado parcial de un lote: solo `POST /api/v1/orders/line-items/returns` con `atomic: false`. Lee el `status` de cada elemento. |
| 304 | No modificado: el `ETag` que enviaste en `If-None-Match` está vigente. |
| 400 | `validation_error`: la consulta o el cuerpo no son válidos. |
| 401 | La clave falta o no se puede usar: `unauthorized` y los códigos `api_key_*`. |
| 402 | `addon_required`: la cuenta no tiene el add-on de ese módulo. |
| 403 | `insufficient_scope` o `forbidden`. |
| 404 | `not_found`: no existe o queda fuera del aislamiento de la clave. |
| 409 | `conflict` (su causa está en `errors[0].code`), `contact_in_use`, `address_in_use` o `insufficient_stock`. |
| 412 | `precondition_failed`: `If-Match` no coincidió. |
| 422 | `idempotency_key_reused`. |
| 429 | `rate_limited`. |
| 500 | `internal_error`. |
| 503 | `service_unavailable`: la funcionalidad está desactivada para la cuenta. |

## Tolera lo que no conoces

Dentro de v1, Filmo añade propiedades a las respuestas y valores a las uniones, como los estados, sin previo aviso. Ignora las propiedades que no uses, trata un valor de enum desconocido como desconocido y no como un error, y no valides las respuestas con un esquema que rechace propiedades adicionales. Los clientes generados con enums cerrados se rompen con los cambios aditivos: consulta [Versionado](https://docs.filmo.io/es/rest-api/guides/versioning).

---

URL canónica: https://docs.filmo.io/es/rest-api/guides/responses  
Última actualización: 2026-10-09