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 (ou em português, com `Accept-Language: pt-BR`). Pode mudar de texto; não compare com ela. Veja Idioma das mensagens.

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 (ela só envia, lê `GET /emails/{id}` dos e-mails que enviou e lê `GET /usage`).	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. Vale para `POST /emails`, o lote, o SMTP, as campanhas e os endereços de teste.	Peça a revisão no painel ou pelo formulário de contato.
`403`	`plan_limit_reached`	O plano não permite mais itens (domínios, inboxes, templates, chaves de API, webhooks, contatos, segmentos, tópicos, formulários, automações, campanhas no mês…) ou não inclui o recurso pedido (envio em lote, agendamento, SMTP, endereços de teste, exportações, anexos, MCP…). Veja a lista de recursos.	Mude de plano ou remova itens.
`403`	`paused_by_plan`	O item (domínio, chave de API, webhook, template, layout, inbox, automação, segmento, tópico ou formulário) passou do limite do plano atual e foi pausado: pode ser lido e excluído, mas não alterado nem usado. Uma chave de API pausada responde isto em toda requisição.	Mude de plano ou exclua outros itens: o item volta sozinho.
`403`	`team_suspended`	A conta foi suspensa pela plataforma que a gerencia.	Fale com essa plataforma.
`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`	`tag_in_use`	A etiqueta é usada por automações e não pode ser excluída.	Tire a etiqueta das automações antes.
`409`	`merge_in_progress`	Outra mesclagem de segmentos ainda está rodando.	Espere terminar e tente de novo.
`409`	`invalid_merge_status`	Só uma mesclagem que falhou pode ser repetida.	Confira o `status` da mesclagem.
`409`	`invalid_segment_type`	O segmento já é estático e não pode ser convertido.	Nada a fazer.
`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.
`410`	`form_closed`	Um envio JSON chegou a um formulário que já não recebe respostas: passou da data de encerramento (`closes_at`), atingiu o limite de envios (`max_submissions`) ou foi pausado com uma mensagem de encerramento. A `message` é a mensagem de encerramento do formulário.	Mostre a mensagem à pessoa; não tente de novo.
`422`	`validation_error`	Algum campo é inválido. A mensagem diz qual.	Corrija o corpo; não repita igual.
`422`	`email_suppressed`	O endereço está na lista de supressão e por isso não vira contato.	Remova o endereço da lista antes, se for o caso.
`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. Também vale quando já há exportações, importações de contatos ou validações de e-mails em andamento demais (a mensagem diz quais), e nos envios a um formulário público (5 por minuto por IP).	Espere `Retry-After` segundos, ou o fim do que está em andamento.
`429`	`daily_quota_exceeded`	A cota diária de envios acabou (volta às 00:00 UTC): o limite diário do plano ou o teto da reputação da conta, o que for menor. Quando é a reputação que limita, a `message` diz o nível e o teto.	Espere. O limite do plano muda com o plano; o teto da reputação cresce a cada dia de envios sem bounces nem reclamações.
`429`	`monthly_quota_exceeded`	A cota mensal de envios acabou (e a reserva do Adicional de envios, se o time tem uma).	Mude de plano, ative o envio além da cota ou, quando o plano oferece, compre o Adicional de envios.
`429`	`verification_credits_exhausted`	Os créditos de validação de e-mails acabaram (ou não bastam para a lista).	Espere o dia 1º, compre o Adicional de validação ou mude de plano.
`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`	`crm_request_failed`	O CRM conectado recusou a chamada da Postal ou não respondeu (teste da conexão, campos, etapas ou sincronização).	Confira o token e o CRM e tente de novo.
`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.
`4xx/5xx`	`application_error`	Outro erro HTTP que não tem nome próprio. O `statusCode` e a `message` dizem o que houve.	Siga o status: `4xx`, corrija a requisição; `5xx`, tente de novo.

#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, 410 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.