Erros

Ramifique pelo status HTTP e por error_code. Nunca por code.

Resumo

Deu certo

Código	Significado
`200`	Requisição atendida. Em `POST /notifications`, uma repetição idempotente
`201`	Recurso criado

Algo na sua requisição precisa mudar

Código	Significado
`400`	Requisição inválida. É o status da maioria das recusas desta API
`401`	Credencial ausente, inválida ou revogada
`402`	Saldo de envios insuficiente
`404`	Recurso não encontrado, inclusive quando pertence a outra organização
`409`	Conflito de contato, de chave idempotente ou de nome de modelo
`413`	Mensagem grande demais para certificar
`422`	Recusado por regra de negócio
`429`	Limite de requisições excedido

Foi do nosso lado

Código	Significado
`500`	Erro interno. Consulte antes de repetir

403 não existe nesta API. Um recurso de outra organização responde 404, e não há modelo de permissão por credencial: toda credencial pode tudo o que a API oferece.

O envelope

Quatro campos, não dois.

{
  "code": 10400,
  "http_code": 400,
  "message": "Invalid request: Missing required fields: template_id",
  "error_code": "MISSING_REQUIRED_FIELD"
}

number | string

Identificador do erro. Numérico (10000 + http_code) na validação genérica, texto nos erros específicos. Não ramifique por este campo.

number

O status HTTP repetido no corpo. Presente quando o erro é devolvido diretamente, ausente quando é lançado e passa pelo tratador geral. Nunca exija este campo no cliente.

string

required

Descrição da falha, para diagnóstico. Não é estável e está em inglês ou em português.

string

O campo para ramificar, quando existe. A maioria dos 400 não o traz: ele marca as recusas que um cliente costuma querer tratar em código, não todas. Quando estiver ausente, use o status HTTP e leia a message para diagnóstico. A lista completa está logo abaixo.

Por que não ramificar por code. Duas operações vizinhas devolvem tipos diferentes no mesmo status: um 404 de GET /templates/{id} traz 10404, e um de GET /notifications/{id} traz "NOT_FOUND". Um if (err.code === 10404) funciona em uma e falha em silêncio na outra.

Os valores de error_code

Sete valores, e é esta a lista inteira.

`error_code`	Status	Onde aparece
`MISSING_REQUIRED_FIELD`	`400`	Campo obrigatório faltando
`INVALID_RECIPIENT`	`400`	Falta o campo de contato exigido pelo canal
`INVALID_SENDER`	`400`	Qualquer recusa do `sender`: ausente, incompleto ou com um dos campos fora do formato
`ORGANIZATION_ID_FORBIDDEN`	`400`	`organization_id` enviado no corpo, ou como parâmetro de consulta
`FILE_TRANSFER_NOT_AVAILABLE_ON_THIS_LANE`	`400`	`file_transfer_id` enviado no envio
`TEMPLATE_CONSTANT_FORBIDDEN`	`400`	`language_code` ou `template_category_type` enviado em `POST /templates`
`IDEMPOTENCY_KEY_REUSED`	`409`	A chave já foi usada com outro corpo, ou com outro arquivo

Todo o resto vem sem error_code, e aí o status HTTP é o que você tem. Em 400 isso inclui: corpo JSON mal formado, channel fora dos dois canais, attachment_id enviado, Idempotency-Key mal formada ou longa demais, telefone fora do formato, recipient_tax_id_type fora do enum, parameters que não é objeto e todas as recusas de multipart/form-data: ordem das partes, partes demais, tipo de arquivo e tamanho.

Se você já tem código lendo code

O campo code carrega uma lista diferente de error_code, às vezes numérica (10000 + http_code) e às vezes em texto. Não ramifique por ele: o tipo muda entre operações vizinhas. Esta tabela existe só para quem já tem código lendo o campo.

`code` em texto	Status
`INVALID_PARAMETERS`	`400`
`NOT_FOUND`	`404`
`CONTACT_CONFLICT`	`409`
`MESSAGE_TOO_LARGE_TO_CERTIFY`	`413`
`TEMPLATE_NOT_APPROVED`	`422`
`SENDER_CHOICE_REQUIRED`	`422`
`INSUFFICIENT_CREDITS`	`402`
`RATE_LIMIT_EXCEEDED`	`429`
`INTERNAL_ERROR`	`500`

400

A validação para no primeiro erro, e a ordem é a desta tabela. Ela importa porque tudo aqui acontece antes da reserva de crédito: nenhum envio é descontado enquanto você acerta o formato. Num multipart/form-data, as recusas de parte vêm antes de todas as outras, porque as partes são lidas primeiro.

`error_code`	`code`	Quando acontece	Ação sugerida
ausente	`10400`	O corpo não é JSON válido, ou não é um objeto	Corrija o JSON. A mensagem é `Invalid request: malformed JSON`
ausente	`10400`	`notification` ou `file` num corpo `application/json`	Para anexar, use `multipart/form-data`
ausente	`10400`	`channel` diferente de `WHATSAPP` e `EMAIL`	Use um dos dois canais
`FILE_TRANSFER_NOT_AVAILABLE_ON_THIS_LANE`	`10400`	`file_transfer_id` enviado	Remova o campo. Envie o arquivo como a parte `file`
ausente	`10400`	`attachment_id` enviado	Remova o campo. O arquivo viaja na própria chamada
`ORGANIZATION_ID_FORBIDDEN`	`10400`	`organization_id` enviado	Remova o campo. A credencial diz a organização
ausente	`10400`	`Idempotency-Key` com caracteres não aceitos, ou acima de 255 caracteres	Use letras, dígitos, `_` e `-`
`MISSING_REQUIRED_FIELD`	`10400`	Campo obrigatório faltando	Corrija a requisição. `sender` também é obrigatório, mas a sua ausência devolve `INVALID_SENDER`, não este código
`INVALID_RECIPIENT`	`10400`	`recipient_email` ausente em `EMAIL`, ou `recipient_phone` ausente no outro canal	Envie o campo de contato do canal
ausente	`10400`	`recipient_email` sem `@`, ou telefone fora de `+CODIGO` com 10 a 15 dígitos	Use `+5511999998888`
ausente	`10400`	`recipient_tax_id_type` diferente de `CPF` ou `CNPJ`	Corrija o tipo
ausente	`10400`	`parameters` não é objeto	Envie `{}` se não houver variáveis
`INVALID_SENDER`	`10400`	`sender` ausente, não é objeto, ou sem `name`, `tax_id` ou `tax_id_type`	Envie os três campos
`INVALID_SENDER`	`10400`	`sender.name` acima de 200 caracteres	Encurte o nome. `sender.name must be at most 200 characters`
`INVALID_SENDER`	`10400`	`sender.name` com `<`, `>`, `"` ou caractere de controle, quebra de linha incluída	Envie só texto simples. `sender.name must be plain text`
`INVALID_SENDER`	`10400`	`sender.tax_id` reprovado no dígito verificador, ou de tipo diferente do declarado	Confira o documento e o `tax_id_type`. `sender.tax_id must be a valid CPF` ou `... CNPJ`
`INVALID_SENDER`	`10400`	`sender.contact_phone` fora de `+CODIGO` com 10 a 15 dígitos	Use `+5511999998888`. `sender.contact_phone must be in format +CODE_PHONE with 10-15 digits (e.g., +5511999998888)`
ausente	`INVALID_PARAMETERS`	Falta uma chave de `parameters`	Consulte `variables` em `GET /templates/{id}`
ausente	`INVALID_PARAMETERS`	Em `WHATSAPP`, o modelo é `DOCUMENT` ou `IMAGE` e o envio veio sem arquivo	Envie como `multipart/form-data`, com a parte `file`
ausente	`INVALID_PARAMETERS`	Em `WHATSAPP`, o modelo é `TEXT` e o envio veio com arquivo	Envie como `application/json`, ou use um modelo `DOCUMENT`

As recusas de multipart/form-data, todas 10400 e todas sem error_code:

Quando acontece	Ação sugerida
A parte `notification` falta, ou veio depois da parte `file`	Envie `notification` primeiro
Uma terceira parte qualquer	São duas partes e só duas: `notification` e `file`
O arquivo passa de 20 MB (PDF) ou 5 MB (imagem)	Reduza o arquivo. Note que é `400`, não `413`
O tipo do arquivo não é `application/pdf`, `image/png` nem `image/jpeg`	Converta o arquivo

ORGANIZATION_ID_FORBIDDEN tem duas redações. Em POST /notifications: organization_id is not accepted on this endpoint: the API key decides the organization. Em POST /templates: organization_id must not be sent as a body field: it is taken from the API key. Mesmo error_code.

401

Quando acontece	Ação sugerida
`Authorization` ausente ou mal formado	Envie `Authorization: Bearer sk_live_...`
Segredo inválido, inexistente ou revogado	Gere uma nova credencial

A resposta é idêntica nos três casos: o Pombo não informa qual deles ocorreu.

402

`code`	Quando acontece	Ação sugerida
`INSUFFICIENT_CREDITS` ou `10402`	Sem envios disponíveis	Compre envios e repita

Único erro que se resolve sem alterar a requisição.

404

`code`	Quando acontece	Ação sugerida
`10404` ou `NOT_FOUND`	O identificador não existe	Confira o valor
`10404` ou `NOT_FOUND`	O recurso pertence a outra organização	Trate como inexistente

Um template_id de outra organização em POST /notifications também responde 404, e não 403: a distinção revelaria que o identificador existe.

{
  "code": 10404,
  "http_code": 404,
  "message": "Template not found"
}

Esse 404 vem direto da rota, então não traz request_id no corpo, ao contrário dos erros que passam pelo tratador geral. O cabeçalho x-request-id está sempre presente: use o cabeçalho.

409

Três causas, e o corpo diz qual é.

`error_code`	`code`	Quando acontece	Ação sugerida
ausente	`CONTACT_CONFLICT`	Os dados do destinatário divergem de um contato já cadastrado	Reconcilie os dados
`IDEMPOTENCY_KEY_REUSED`	`10409`	A mesma `Idempotency-Key` com um corpo diferente	Use uma chave nova
ausente	`10409`	Nome de modelo já usado, em `POST /templates`	Escolha outro nome. Veja a ressalva abaixo

Um nome de modelo repetido quase nunca dá 409. O caminho normal é o Pombo renomear sozinho, acrescentando -2, -3, e devolver 201 com um modelo novo. Como a API não lista modelos, esse modelo fica inalcançável. Veja Idempotência.

Conflito de contato. Os contatos são unificados pelo tax_id, então o mesmo CPF com um telefone diferente conflita em vez de criar uma segunda pessoa. O corpo traz campos extras para você reconciliar.

{
  "code": "CONTACT_CONFLICT",
  "http_code": 409,
  "message": "Contato com este CPF já existe com um número de telefone diferente",
  "conflict_type": "tax_id_phone_mismatch",
  "existing_contact": {
    "contact_id": "PBD_CNT_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
    "name": "Maria Silva",
    "tax_id": "12345678901",
    "phone": "+5511999998888"
  },
  "input_data": {
    "name": "Maria S. Silva",
    "phone": "+5511888887777",
    "tax_id": "12345678901",
    "tax_id_type": "CPF"
  }
}

string

tax_id_phone_mismatch, phone_tax_id_mismatch ou name_mismatch.

object

O contato já cadastrado.

object

Os dados enviados, para comparação.

Corrija a divergência antes de repetir. A mesma requisição devolve o mesmo conflito. Chave idempotente reutilizada. Esse corpo vem sem http_code, porque é lançado e não devolvido.

{
  "code": 10409,
  "message": "Idempotency-Key already used with a different request",
  "error_code": "IDEMPOTENCY_KEY_REUSED"
}

A chave já foi usada com outro corpo. Veja Idempotência.

413

`code`	Quando acontece	Ação sugerida
`MESSAGE_TOO_LARGE_TO_CERTIFY`	A mensagem renderizada excede o limite de certificação	Reduza o texto ou o HTML das variáveis

Nada foi enviado e nada foi cobrado. A message informa o tamanho e o limite. É o único 413 desta API. Um anexo grande demais é 400, não 413.

422

`code`	Quando acontece	Ação sugerida
`TEMPLATE_NOT_APPROVED`	O modelo não está `APPROVED`	Aguarde a aprovação
`SENDER_CHOICE_REQUIRED`	A organização tem mais de um endereço de envio utilizável: os dedicados verificados mais o compartilhado do Pombo	Fale com o suporte do Pombo. Nenhuma chamada desta API resolve isso
`10422`	Conteúdo recusado pela política, em `POST /templates`	Revise o texto do modelo

O 10422 só acontece na criação do modelo, nunca no envio, e o corpo não diz qual regra falhou: traz só Content policy violation detected.

429

`code`	Quando acontece	Ação sugerida
`RATE_LIMIT_EXCEEDED`	Limite de requisições excedido	Aguarde e repita, veja Limites de uso

500

O corpo é reduzido e não traz http_code.

{
  "message": "Internal Server Error",
  "code": "INTERNAL_ERROR",
  "request_id": "req_01M1C5ZKGBGRNW6QHXTP2EM7Y7"
}

O request_id é o mesmo valor do cabeçalho x-request-id. Registre-o.

Um 500 em POST /notifications não garante que nada foi enviado. Consulte antes de repetir: uma notificação extrajudicial emitida não pode ser cancelada.

Depuração

Toda resposta traz o cabeçalho x-request-id.

x-request-id: req_01M1C5ZKGBGRNW6QHXTP2EM7Y7

Registre esse valor junto com os seus próprios logs. É por ele que o suporte encontra a requisição exata, e sem ele a investigação começa por adivinhação. Ao abrir um chamado, informe o x-request-id, o horário e o notification_id, quando houver.

Referência da API

Modelos

Notificações

Resumo

O envelope

Os valores de error_code

400

401

402

404

409

413

422

429

500

Depuração

​Resumo

​O envelope

​Os valores de error_code

​400

​401

​402

​404

​409

​413

​422

​429

​500

​Depuração

Resumo

O envelope

Os valores de error_code

400

401

402

404

409

413

422

429

500

Depuração