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.