CONCEITOS

Respostas e tratamento de erros

Diferencie uma requisição processada, uma mensagem aceita e uma falha que precisa de investigação.

Envelope de resposta

Em sucesso, leia success=true e data. Campos de compatibilidade como send_id, deleted, schedule_id e hash também podem aparecer no topo. O request_id correlaciona a chamada para suporte.

Os JSONs da referência são exemplos representativos, não dados reais. Campos opcionais e metadados do plano podem variar. Tolere campos extras e valores nulos quando documentados.

Falhas têm código e protocolo

Use o status HTTP, code e request_id, não a comparação exata do texto de error. Mensagens podem mudar para melhorar segurança e clareza. Uma falha não deve ser convertida em sucesso local.

O erro pode incluir send_id, sent e total quando um envio foi tentado. Guarde esses identificadores para investigar o resultado; não exponha diagnósticos internos ao usuário final.

Erro · exemplo

{
  "success": false,
  "error": "Identificador da instancia obrigatorio para consultar o status.",
  "code": "INSTANCE_REQUIRED",
  "request_id": "44444444-4444-4444-8444-444444444444"
}

Timeout e tentativas

Em HTTP 429 aguarde antes de tentar novamente. Em erros temporários, use espera progressiva apenas quando a operação puder ser repetida com segurança.

A API não disponibiliza uma chave pública de idempotência. Não repita automaticamente criação de instâncias, envios ou agendamentos depois de timeout. Para consultas, use um intervalo moderado, sem polling em loop apertado.

Códigos HTTP e erros públicos mais comuns
HTTP	Código / condição
`400`	`INSTANCE_REQUIRED / REQUEST_REJECTED` Parâmetro ausente, inválido ou operação recusada.
`401`	`REQUEST_REJECTED` AuthKey ausente, inválida ou revogada.
`403`	`REQUEST_REJECTED` Acesso não autorizado, assinatura ou limite do plano.
`404`	`INSTANCE_NOT_FOUND / REQUEST_REJECTED` Instância não encontrada para a empresa autenticada.
`405`	`METHOD_NOT_ALLOWED` Use POST. OPTIONS é reservado ao preflight autorizado.
`413`	`PAYLOAD_TOO_LARGE` Corpo JSON acima do limite de 16 MiB.
`415`	`JSON_CONTENT_TYPE_REQUIRED` Envie Content-Type: application/json.
`423`	`RECIPIENT_QUARANTINED` Destinatário bloqueado pela proteção de quarentena.
`429`	`RATE_LIMITED` Limite de requisições atingido; aguarde antes de tentar novamente.
`502`	`INTERNAL_ERROR / AUTOMATIZAIPRO_DELETE_REJECTED` A operação não foi confirmada pelo serviço de mensagens.
`503`	`AUTOMATIZAIPRO_DELETE_UNAVAILABLE / AUTOMATIZAIPRO_DELETE_LOOKUP_UNAVAILABLE` Não foi possível confirmar a limpeza da instância.
`503`	`RECIPIENT_QUARANTINE_UNAVAILABLE` Proteção de destinatários temporariamente indisponível.