Skip to main content
Todas as respostas de erro seguem o mesmo padrão das demais APIs (SMS, E-mail, WhatsApp, Push): camelCase e estrutura unificada.

​
Formato do body de erro

{
  "success": false,
  "error": "Bad Request",
  "message": "Mensagem legível para o desenvolvedor.",
  "code": "CODIGO_OPCIONAL",
  "details": [
    { "field": "nomeDoCampo", "message": "Descrição do erro no campo." }
  ],
  "missingVariables": ["nome", "codigo"]
}
CampoTipoSempre presenteDescrição
successbooleanSimSempre false em erro.
errorstringSimTipo HTTP do erro (ex.: Bad Request, Forbidden).
messagestringSimMensagem legível.
codestringNãoCódigo para lógica (ex.: WORKSPACE_BLOCKED, PLAN_LIMIT_CREDITS).
detailsarrayNãoLista de { field, message } para erros de validação por campo.
missingVariablesstring[]NãoEm 400 por variáveis faltando: lista de variáveis obrigatórias que não foram enviadas.

​
Códigos HTTP e quando ocorrem

  • to vazio ou com mais de 100 itens; destinatário não é telefone nem e-mail válido.
  • template ausente ou template não encontrado.
  • Variáveis obrigatórias faltando no objeto variables (resposta inclui missingVariables).
  • Canal WhatsApp sem instanceId e sem instância padrão no workspace (details[].field: instanceId).
  • Canal E-mail sem from e sem domínio padrão no workspace (details[].field: from).
  • Domínio de e-mail não verificado (code: DOMAIN_NOT_VERIFIED ou DEFAULT_DOMAIN_NOT_VERIFIED).
  • Canal sms: texto final (após substituir variáveis) com menos de 9 caracteres ou conteúdo bloqueado por política (code: SMS_MESSAGE_TOO_SHORT ou UNSAFE_SMS_CONTENT; details costuma apontar template.smsContent ou message).
Use o header Authorization: Bearer sk_live_xxxxx ou x-api-key: sk_live_xxxxx.
Códigos possíveis: WORKSPACE_BLOCKED, INSUFFICIENT_CREDITS, INSUFFICIENT_CREDITS_OR_BALANCE, API_KEY_SPEND_LIMIT_EXCEEDED.
  • Falta de escopo na API Key (whatsapp:send, sms:send, email:send conforme os canais).
  • Créditos insuficientes: code: INSUFFICIENT_CREDITS.
  • Limite de plano: code: PLAN_LIMIT_CREDITS.
  • Instância não permitida para esta API Key (acesso à instância negado).
Template não existe ou não pertence ao workspace; ou instância WhatsApp não encontrada/inativa.
code: SMS_DUPLICATE_RECENT. Mesmo número e mesma mensagem em menos de 1 minuto. Aguarde antes de reenviar.
E-mail: provedor não configurado. WhatsApp: instância desconectada ou indisponível.

​
Exemplos (camelCase)

400 — SMS muito curto (template) 
{
  "success": false,
  "error": "Bad Request",
  "message": "SMS message must be at least 9 characters.",
  "code": "SMS_MESSAGE_TOO_SHORT",
  "details": [
    { "field": "template.smsContent", "message": "SMS message must be at least 9 characters." }
  ]
}
400 — Variáveis faltando 
{
  "success": false,
  "error": "Bad Request",
  "message": "Missing required template variables",
  "details": [{ "field": "variables", "message": "Missing variable: nome" }],
  "missingVariables": ["nome"]
}
402 — Workspace bloqueado 
{
  "success": false,
  "error": "Payment Required",
  "message": "Trial ended or plan expired. Choose a plan to continue.",
  "code": "WORKSPACE_BLOCKED"
}
402 — Limite da API Key atingido 
{
  "success": false,
  "error": "Payment Required",
  "message": "API key spend limit exceeded.",
  "code": "API_KEY_SPEND_LIMIT_EXCEEDED"
}
403 — Créditos insuficientes 
{
  "success": false,
  "error": "Forbidden",
  "message": "Insufficient credits.",
  "code": "INSUFFICIENT_CREDITS"
}
409 — SMS duplicado 
{
  "success": false,
  "error": "Conflict",
  "message": "Same SMS (same recipient and message) was sent less than 1 minute ago. Wait before retrying.",
  "code": "SMS_DUPLICATE_RECENT"
}