---
title: "Convenzioni"
description: "Paginazione, date, limiti e intestazioni della risposta."
canonical: "https://atelier201.com/docs/it/api/conventions"
updated: "2026-11-06"
---

# Convenzioni

## Buste

Ogni risposta riuscita ha il formato `{ "data": ..., "request_id": "..." }`. Quando segnali un problema, cita il
`request_id`: serve a trovare la riga corrispondente nel log.

## Paginazione

Basata su cursore, mai su offset. Nella richiesta successiva, passa come `cursor`
il valore `next_cursor` della risposta precedente.

Con un offset si percorre di nuovo l'intero prefisso a ogni pagina e, peggio ancora, si SALTANO righe se viene inserito qualcosa tra due richieste. Di conseguenza, un client che sfoglia un elenco mentre vengono aggiunti elementi ne perde alcuni senza accorgersene. Con un cursore questo non succede.

## Input flessibili

`limit` viene adeguato al limite massimo anziché essere rifiutato: se ne chiedi 500, ne ottieni 100 e la risposta indica il limite applicato. Un limite non numerico genera comunque un errore, perché è un dato errato, non una scelta intenzionale.

Le date accettano `2026-07-01` o un timestamp ISO 8601 completo. Una data senza orario nel parametro `to` indica la FINE di quel giorno, come si intende normalmente con «fino al 31».

## Scrittura sicura

Ogni scrittura che sostituisce qualcosa può specificare cosa si aspetta di sostituire. Invia `expected_hash` del file o della voce che hai letto: se è cambiata nel frattempo, la modifica viene rifiutata con `409 conflict`. Per pubblicare, ripristinare e annullare la pubblicazione, passa `expected_generation` della versione letta, così modifichi solo lo stato che hai esaminato. Entrambi i tipi di conflitto includono in `error.details` le informazioni necessarie per rileggere i dati.

## Operazioni lunghe

Una build restituisce subito lo stato `queued`; continua a interrogarne lo stato finché non diventa `ready`, `failed` o `cancelled`. Sono tutti stati finali: interrompi le richieste quando ne compare uno.

## Limiti di frequenza

Si applicano cinque limiti, a protezione di aspetti diversi: il volume di richieste per credenziale, una breve finestra di picco, il volume per IP, la registrazione dei client e, in particolare, i FALLIMENTI di autenticazione. Ogni risposta riporta nelle intestazioni il budget residuo; una risposta 429 include `Retry-After`.