Conceitos

Erros

Todas as respostas de erro têm o mesmo formato, com um nome estável para você tratar no código.

#Formato

Respostas com status 2xx deram certo. Em caso de erro, o corpo é sempre um JSON com três campos:

422Resposta de erro

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Missing `subject` field."
}

Campo	Descrição
`statusCode`	O mesmo status HTTP da resposta.
`name`	Código estável do erro, em inglês. Use este campo no seu código.
`message`	Explicação para pessoas, em inglês. Pode mudar de texto; não compare com ela.

Alguns erros trazem um campo extra: errors. No envio público de formulários, é um objeto com as mensagens de cada campo; nas automações, uma lista com cada problema da definição (step_id e message).

#Códigos de erro

Status	Nome	Quando acontece	O que fazer
`400`	`invalid_idempotency_key`	A `Idempotency-Key` está vazia ou passa de 256 caracteres.	Corrija a chave.
`401`	`missing_api_key`	Faltou o cabeçalho `Authorization`.	Envie `Authorization: Bearer ps_…`.
`401`	`restricted_api_key`	Uma chave só de envio chamou um endpoint que exige acesso total.	Use uma chave de acesso total.
`403`	`invalid_api_key`	A chave não existe ou foi excluída.	Confira a chave ou crie outra.
`403`	`restricted_api_key`	A chave é restrita a outro domínio.	Use o domínio da chave ou outra chave.
`403`	`validation_error`	O domínio do remetente não está verificado, não tem envio ativo ou não é do seu time.	Verifique o domínio.
`403`	`sending_paused`	Os envios do time foram pausados por taxa alta de bounces ou reclamações.	Fale com [email protected].
`403`	`plan_limit_reached`	O plano não permite mais domínios, inboxes, contatos, segmentos, campanhas no mês ou o recurso pedido.	Mude de plano ou remova itens.
`403`	`origin_not_allowed`	Um formulário recebeu um envio de um site fora dos `allowed_domains`.	Inclua o domínio no formulário.
`404`	`not_found`	O recurso não existe, é de outro time ou a rota não existe.	Confira o ID e o caminho.
`405`	`method_not_allowed`	O caminho existe, mas não com esse método.	Confira o método.
`409`	`invalid_idempotent_request`	A mesma `Idempotency-Key` foi usada com outro corpo.	Use uma chave nova por envio.
`409`	`concurrent_idempotent_requests`	Uma requisição com a mesma chave ainda está em andamento.	Espere e tente de novo.
`409`	`segment_in_use`	O segmento recebe os contatos de um formulário e não pode ser excluído.	Troque o segmento do formulário antes.
`409`	`invalid_broadcast_status`	A campanha (`/broadcasts`) não está num status que permite a ação: editar ou excluir uma que já saiu, enviar uma cancelada, cancelar um rascunho.	Confira o `status` da campanha.
`422`	`validation_error`	Algum campo é inválido. A mensagem diz qual.	Corrija o corpo; não repita igual.
`422`	`ai_refused`	A IA recusou o pedido.	Reescreva o pedido.
`429`	`rate_limit_exceeded`	Passou do limite de requisições por segundo do plano.	Espere `Retry-After` segundos.
`429`	`daily_quota_exceeded`	A cota diária de envios acabou (volta às 00:00 UTC).	Espere ou mude de plano.
`429`	`monthly_quota_exceeded`	A cota mensal de envios acabou.	Mude de plano ou ative o envio além da cota.
`429`	`ai_credits_exhausted`	Os créditos de IA do mês acabaram.	Espere o dia 1º ou mude de plano.
`500`	`internal_server_error`	Erro inesperado na Postal.	Tente de novo com espera crescente.
`502`	`ai_error`	A IA não devolveu uma resposta válida.	Tente de novo.
`503`	`ai_unavailable`	O serviço de IA está ocupado.	Tente de novo em instantes.
`503`	`ai_not_configured`	O assistente de IA está indisponível.	Tente mais tarde.

#Quando tentar de novo

Tente de novo em 429 rate_limit_exceeded, 409 concurrent_idempotent_requests, 5xx e falhas de rede (timeout, conexão recusada). Espere um pouco mais a cada tentativa (1 s, 2 s, 4 s…) e respeite o Retry-After quando vier.
Não repita igual em 400, 401, 403, 404 e 422: a resposta vai ser a mesma até você corrigir a requisição ou a configuração.
Em envios, mande sempre uma Idempotency-Key: se a primeira tentativa chegou a dar certo, a repetição devolve a mesma resposta sem enviar de novo.