Idempotência e limites

Repita chamadas com segurança e respeite os limites de taxa.

​

Idempotência

Envie o header Idempotency-Key com um valor único por operação, como um UUID.

• Repetir a chamada com a mesma chave e o mesmo corpo devolve a primeira resposta, com o header Idempotent-Replayed: true, sem consultar nem cobrar de novo.
• A mesma chave com outro corpo retorna 422 idempotency_mismatch.

Use isso para repetir chamadas depois de timeouts de rede sem risco de cobrança duplicada.

​

Limites de taxa

O padrão é de 600 requisições por minuto por rota e endereço. Toda resposta traz RateLimit-Remaining. Ao exceder o limite, você recebe 429 com Retry-After, em segundos.

​

Limites da organização

Em Faturamento, no console, a organização pode definir para cada ambiente:

Limite	Ao atingir
Requisições por minuto	429 rate_limited, com Retry-After
Requisições por mês	429 monthly_quota_exceeded até o mês seguinte (UTC)
Gasto mensal	402 budget_exceeded na consulta que passaria do valor

Os limites de requisições valem para todas as chamadas feitas com chave de API, somadas entre as chaves da organização. A Omni-Ward também pode definir um teto para a sua conta; nesse caso vale o menor valor, e a organização não consegue definir um limite acima do teto.

​

Versionamento

A versão fica no caminho (/v1). Novos campos e serviços não são mudanças incompatíveis: ignore campos desconhecidos na resposta. Mudanças incompatíveis exigem uma nova versão.