Comece por aqui

Erros e limites

Identifique erros, respeite os limites e recupere chamadas com segurança.

API v1•REST · JSON · Bearer token

Formato dos erros

Erros retornam um objeto error. Use code para tratar o caso e requestId ou o header X-Request-Id ao investigar uma chamada.

{
  "error": {
    "code": "forbidden",
    "message": "A chave não tem permissão para esta operação.",
    "requestId": "55555555-5555-4555-8555-555555555555"
  }
}

Códigos HTTP

Status	Significado
`400`	Solicitação inválida
`401`	Chave inválida, expirada ou revogada
`403`	Permissão insuficiente ou origem de navegador
`404`	Recurso não encontrado
`409`	Conflito, agente pausado ou solicitação em processamento
`413`	Corpo acima do limite
`415`	Tipo de conteúdo inválido
`429`	Limite de chamadas excedido
`502`	Falha do provedor
`503`	Serviço indisponível

Limites

Recurso	Limite
Chamadas autenticadas	120 por minuto, por chave
Envio de mensagens	30 por minuto, por chave
Uploads	10 por minuto, por chave
Corpo JSON / mensagem	64 KiB / 6.000 caracteres
Arquivo / conta	20 MiB / 100 MiB ou 100 arquivos
Paginação	50 por padrão; máximo de 100

Em 429, aguarde o período do header Retry-After. Uma proteção adicional limita o tráfego de entrada. Não divida as chamadas entre chaves para contornar os limites.

Idempotência de mensagens

Envie um UUID exclusivo em Idempotency-Key. A reserva e o resultado permanecem por pelo menos 24 horas. O mesmo corpo e a mesma chave reutilizam o resultado; o header Idempotency-Replayed: true identifica a reutilização. Corpo diferente com a mesma chave retorna 409.

Se o processo for interrompido antes de concluir, o resultado pode ser incerto. A API mantém a reserva e retorna 409, evitando executar ferramentas novamente. Falhas concluídas também são preservadas. Não use uma chave nova para repetir automaticamente uma mensagem.

As chamadas de mensagem não mantêm histórico entre solicitações. O resultado é armazenado temporariamente para idempotência; o registro técnico de acesso, sem corpo ou token, é mantido por 30 dias.