---
title: "Convenções"
description: "Paginação, datas, limites e cabeçalhos de resposta."
canonical: "https://atelier201.com/docs/pt/api/conventions"
updated: "2026-11-06"
---

# Convenções

## Estrutura das respostas

Toda resposta bem-sucedida segue o formato `{ "data": ..., "request_id": "..." }`. Inclua o
`request_id` ao relatar um problema: é por ele que a linha do log é localizada.

## Paginação

Baseada em cursor, nunca em deslocamento. Envie o `next_cursor` da resposta anterior
novamente como `cursor`.

Com deslocamento, o prefixo inteiro é percorrido em cada página e, pior, linhas são
IGNORADAS se algo for inserido entre duas solicitações. Assim, um cliente que percorre uma lista
que está sendo alterada deixa itens passarem sem aviso. Com um cursor, isso não acontece.

## Entradas flexíveis

`limit` é ajustado ao limite permitido, não rejeitado: se você solicitar 500, receberá 100, e a resposta
informará o limite aplicado. Um limite que não seja numérico ainda resulta em erro,
pois isso é um engano, não uma intenção.

As datas aceitam `2026-07-01` ou um registro de data e hora completo no formato ISO 8601. Uma data sem horário no
lado `to` corresponde ao FIM desse dia, como alguém quer dizer ao falar em "até o dia 31".

## Gravação segura

Toda gravação que substitui algo pode informar o que espera substituir. Envie o
`expected_hash` de um arquivo ou uma entrada que você leu; a alteração será rejeitada com
`409 conflict` se o conteúdo tiver mudado. Para publicar, reverter e retirar da publicação, informe o
`expected_generation` que você leu, para alterar somente o estado que revisou. Os dois conflitos incluem em `error.details` o que você precisa consultar novamente.

## Operações demoradas

Uma build retorna imediatamente no estado `queued`; consulte-a até que fique
`ready`, `failed` ou `cancelled`. Esses estados são finais: pare de consultar quando encontrar um deles.

## Limites de requisições

Há cinco limites, cada um protegendo algo diferente: volume por credencial,
uma janela curta de pico, volume por IP, registro de clientes e FALHAS
especificamente de autenticação. Toda resposta inclui nos cabeçalhos o saldo restante;
uma resposta 429 inclui `Retry-After`.