Convenciones
Paginación, fechas, límites y cabeceras de respuesta.
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.