Códigos de erro

Formato da resposta de erro

Toda resposta de erro (exceto as de autenticação, veja abaixo) segue este formato:

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Descrição legível do que deu errado.",
  "type": "validation",
  "timestamp": "2026-10-19T20:00:00.000Z",
  "statusCode": 422,
  "requestId": "abc123",
  "details": { "code": "CHANNEL_NOT_ENABLED" }
}

code é um bucket amplo (VALIDATION_ERROR, UNAUTHORIZED, NOT_FOUND, CONFLICT, RATE_LIMITED, BUSINESS_RULE_VIOLATION, INTERNAL_ERROR). details.code, quando presente, é o código específico da regra de negócio que falhou — é esse que você deve usar para decidir o que fazer no seu código, não o code de nível superior.

Erros de autenticação (401, antes mesmo do corpo ser validado) vêm num formato um pouco mais enxuto, sem details/timestamp:

{
  "status": "error",
  "statusCode": 401,
  "code": "API_KEY_INVALID",
  "message": "...",
  "type": "auth"
}

Erros comuns a qualquer canal

code (nível superior)	details.code	HTTP	Quando acontece
—	API_KEY_MISSING	401	Header Authorization: Bearer <token> ausente.
—	API_KEY_MALFORMED	401	Token não está no formato pln_<env>_<key_id>_<secret>.
—	API_KEY_INVALID	401	key_id não existe, ou o secret não confere.
—	API_KEY_REVOKED	401	A key foi revogada por um administrador.
—	API_KEY_EXPIRED	401	A key passou da data de expiração.
—	APPLICATION_SUSPENDED	401	A aplicação dona da key está suspensa.
VALIDATION_ERROR	—	422	Corpo da requisição não passa na validação (campo ausente, tipo errado, CRLF em campo sensível, etc.) — details.errors traz as mensagens específicas.
VALIDATION_ERROR	IDEMPOTENCY_KEY_MISSING	422	Header Idempotency-Key ausente.
—	CHANNEL_NOT_ENABLED	422	O channel enviado existe, mas não está habilitado neste ambiente.
—	TEMPLATE_NOT_FOUND	404	Nenhum template com o templateSlug/channel enviados.

Erros específicos de canal

• E-mail: SENDER_NOT_VERIFIED.
• Telegram: CHANNEL_NOT_CONFIGURED.
• WhatsApp: CHANNEL_NOT_CONFIGURED (exige token + instance_id do Intera).

Idempotência

Reenviar a mesma combinação de aplicação + Idempotency-Key não é um erro — a API devolve 202 com o mesmo id/status da primeira chamada, sem criar uma segunda mensagem.