---
title: "Convenciones"
description: "Paginación, fechas, límites y cabeceras de respuesta."
canonical: "https://atelier201.com/docs/es/api/conventions"
updated: "2026-11-06"
---

# Convenciones

## Envoltorios

Todas las respuestas satisfactorias tienen este formato: `{ "data": ..., "request_id": "..." }`. Incluye `request_id` cuando informes de un problema: es la forma de localizar una línea del registro.

## Paginación

Se basa en cursores, nunca en desplazamientos. Pasa como `cursor` el valor `next_cursor` de la respuesta anterior.

Con un desplazamiento se recorre todo el prefijo en cada página y, lo que es peor, se OMITEN filas si se inserta algo entre dos solicitudes. Así, un cliente que pagina una lista mientras se modifica puede saltarse elementos sin avisar. Con un cursor, no.

## Entradas flexibles

`limit` se ajusta al máximo permitido, no se rechaza: si pides 500, recibes 100 y la respuesta indica el límite aplicado. En cambio, si el límite no es un número, la solicitud falla: eso es un error, no una intención.

Se aceptan fechas como `2026-07-01` o marcas de tiempo completas en formato ISO 8601. En el parámetro `to`, una fecha sin hora corresponde al FINAL de ese día, que es lo que se entiende por «hasta el día 31».

## Escritura segura

En cualquier operación de escritura que sustituya algo, puedes indicar qué versión esperas sustituir. Envía el `expected_hash` del archivo o la entrada que has consultado y el cambio se rechazará con `409 conflict` si ha cambiado. Para publicar, revertir o retirar la publicación, indica el `expected_generation` que has consultado, de modo que solo cambies el estado que has revisado. En ambos casos, `error.details` incluye la información que necesitas volver a consultar.

## Operaciones largas

Una compilación devuelve de inmediato el estado `queued`. Consulta su estado hasta que sea `ready`, `failed` o `cancelled`. Son estados finales: deja de consultar cuando veas uno.

## Límites de solicitudes

Se aplican cinco límites, cada uno para proteger algo distinto: el volumen por credencial, un intervalo breve de ráfagas, el volumen por IP, el registro de clientes y, específicamente, los FALLOS de autenticación. Todas las respuestas incluyen en sus cabeceras el saldo restante; las respuestas `429` incluyen `Retry-After`.