Erros

Os erros respondem com o código HTTP correspondente e um corpo JSON. Há duas formas:

Erros de negócio (o que você pediu não pode ser feito): trazem um message para uma pessoa e, quando seu código precisa distingui-los, um code estável.

JSON

{ "statusCode": 409, "code": "CONTACT_PHONE_EXISTS", "message": "Ya existe un contacto con ese teléfono.", "contactId": "0b1c2d3e-…", "fullName": "Laura Pérez" }

Erros de validação (o corpo ou os parâmetros não cumprem o contrato): statusCode 400 e uma lista de mensagens, uma por campo. Um campo ou parâmetro desconhecido também é rejeitado (property x should not exist): assim um erro de digitação não passa como «sem filtro».

JSON

{ "statusCode": 400, "message": ["primaryPhone must be shorter than or equal to 32 characters"], "error": "Bad Request" }

Códigos HTTP

Código	Quando
400	Validação, ou uma ação que não cabe no estado atual (campanha já enviada, sem destinatários, saldo insuficiente, data no passado)
401	Chave inválida, anulada ou expirada
403	Permissão que falta ou rota não aberta a chaves
404	O recurso não existe ou não é da sua organização
409	Conflito: telefone já usado por outro contato, identidade de canal já vinculada, contato com histórico
429	Limite de requisições
5xx	Erro nosso: tente de novo com espera crescente e, se persistir, fale conosco

Códigos de erro estáveis

`code`	HTTP	Significado
`API_KEY_INVALID`	401	A chave não existe, está escrita errado ou foi anulada
`API_KEY_EXPIRED`	401	A chave expirou: crie outra
`API_KEY_SCOPE_MISSING`	403	A rota exige uma permissão que a chave não tem; o `message` diz qual
`API_KEY_NOT_ALLOWED_HERE`	403	A rota não está aberta a chaves de API
`API_KEY_RATE_LIMITED`	429	Mais de 600 requisições em um minuto com essa chave
`CONTACT_PHONE_EXISTS`	409	Já há um contato com esse telefone; a resposta traz `contactId` e `fullName`
`CONTACT_HAS_HISTORY`	409	Não se exclui um contato com conversas, campanhas ou vendas
`CAMPAIGN_VARIABLES_REQUIRED`	400	O modelo tem variáveis e a campanha não diz de onde elas saem
`PHONE_NUMBER_NOT_OWNED`	409	O número remetente não pertence à sua organização

Os demais erros de negócio chegam só com message; na referência de cada rota estão os mais frequentes. Trate os code como estáveis: não mudarão dentro da versão. Os message podem melhorar com o tempo e são pensados para exibir, não para comparar.

Saldo insuficiente

Enviar uma campanha debita o lote da wallet antes de chamar a Meta. Se não for suficiente, POST /campaigns/{id}/send responde 400 com «Saldo insuficiente en la wallet.» e a campanha fica como estava; se o saldo acabar no meio de um envio escalonado, a campanha é pausada com esse motivo em stopReason e é retomada com POST /campaigns/{id}/resume depois de recarregar. Consulte GET /campaigns/{id}/preview-cost antes de enviar: wallet.sufficient informa isso sem tentar o envio.