Erros

Toda falha do broker chega ao SDK como um BrokerApiError, nunca um erro cru de fetch ou payload de provider. O code pertence a uma união fechada — você pode tratá-lo exaustivamente com switch.

A forma do erro

import { BrokerApiError } from '@wabroker/sdk'

try {
  await wa.messages.send('5511999999999', input) // pelo número do canal
} catch (err) {
  if (err instanceof BrokerApiError) {
    err.code        // BrokerApiErrorCode (união fechada)
    err.httpStatus  // status HTTP; 0 quando não houve resposta (rede/timeout)
    err.retryable   // seguro repetir automaticamente?
    err.retryAfter  // segundos a esperar (só em rate_limited/queue_saturated)
    err.traceId     // correlacionador — sempre presente numa resposta do broker
  }
  throw err
}

A WabrokerApiException (.NET) expõe Code, HttpStatus, Retryable e RetryAfter — mas não um TraceId: o correlacionador só existe no traceId do BrokerApiError (TS).

O envelope de erro

Todo erro HTTP do broker (/v1/* e /admin/v1/*) responde com o mesmo envelope JSON — aqui um rate_limited (429), que ilustra retryAfter:

{
  "code": "rate_limited",
  "message": "Limite de envio do número atingido",
  "retryable": true,
  "retryAfter": 30,
  "traceId": "tr_01hz..."
}

• code / message / retryable sempre presentes.
• retryAfter (segundos) só em rate_limited e queue_saturated — os dois únicos códigos de back-pressure.
• traceId sempre presente — a borda do broker carimba toda requisição com um trace_id (o mesmo x-trace-id do chamador, quando enviado) e o middleware de erro preenche traceId em toda resposta que ainda não o carregue, inclusive um 500 desconhecido. Registre-o nos seus logs para agilizar o suporte.
• errors[] só aparece em validation_error: uma lista de { field, rule, message } — field é o dot-path do campo no corpo (ex.: content.language), rule é a regra do validador que falhou (ex.: invalid_type, too_small), message é a descrição curada em pt-BR (nunca o texto cru do validador, nunca payload de provider).

validation_error vs unsupported_capability

Os dois respondem 422, mas significam coisas diferentes:

• validation_error — o corpo está malformado: campo ausente, tipo errado, enum inválido. Detectado pela validação do schema, antes de qualquer regra de negócio. errors[] aponta exatamente quais campos corrigir.
• unsupported_capability — o corpo está bem formado, mas o canal não suporta o recurso pedido (ex.: enviar mídia de vídeo por um provider não-oficial sem esse suporte). Não há campo a corrigir — o chamador troca de estratégia (outro tipo de conteúdo, outro canal). Nunca carrega errors[].

Exemplo real — enviar um template sem o campo obrigatório `language`:

{
  "code": "validation_error",
  "message": "Campo inválido: content.language",
  "retryable": false,
  "traceId": "tr_...",
  "errors": [
    { "field": "content.language", "rule": "invalid_type", "message": "Campo obrigatório" }
  ]
}

Tratando `errors[]` nos dois SDKs:

if (err instanceof BrokerApiError && err.code === 'validation_error') {
  for (const e of err.errors ?? []) {
    console.error(`${e.field}: ${e.message} (${e.rule})`)
  }
}

Tratar por código

if (err instanceof BrokerApiError) {
  switch (err.code) {
    case 'rate_limited':
    case 'queue_saturated':
      await sleep((err.retryAfter ?? 1) * 1000)
      // ... reenfileire e tente de novo
      break
    case 'outside_24h_window':
      // troque para um template aprovado
      break
    case 'channel_disconnected':
      // reconecte o canal; a mensagem pode ser retentada
      break
    case 'unauthorized':
      // API key inválida — não adianta repetir com a mesma key
      break
    default:
      if (err.retryable) scheduleRetry()
      else reportPermanentFailure(err)
  }
}

Códigos do broker

retryable indica se repetir a mesma requisição pode ter sucesso. rate_limited e queue_saturated sempre acompanham retryAfter.

Na Wabroker.Sdk (.NET), os mesmos códigos aparecem como o enum WabrokerErrorCode (PascalCase — ex.: recipient_suppressed vira WabrokerErrorCode.RecipientSuppressed).

Códigos do lado cliente

Além dos códigos do broker, o SDK reporta duas falhas que acontecem antes de o broker responder em contrato. Nesses casos httpStatus é 0.

Boas práticas

• Sempre cheque err instanceof BrokerApiError antes de ler code.
• Respeite retryAfter em 429 — não faça busy-retry.
• Registre traceId nos seus logs para agilizar o suporte.
• Trate o default do switch por retryable, para lidar com códigos futuros com segurança.