Erros

Todo corpo de resposta 4xx e 5xx usa o mesmo envelope:

{
  "error": {
    "code": "channel_unavailable",
    "message": "Channel is not connected. Re-pair to continue.",
    "details": { "channel_id": "..." }
  },
  "request_id": "req_01J..."
}

Faça match no code — ele é o contrato estável. message é legível por humanos e pode mudar entre releases. details é opcional e específico de cada código.

O conjunto completo de códigos vem no contrato Zod ERROR_CODES. A tabela abaixo é canônica.

Auth / identidade

Código	Quando você vai ver
`auth_missing`	Nenhum header `Authorization` enviado.
`auth_invalid`	O token bearer não corresponde a nenhuma chave ativa.
`auth_malformed`	Header presente mas não `Bearer …`, ou formato de token errado.
`auth_expired`	A chave foi revogada ou expirou.
`auth_no_email`	O token de sessão do dashboard não tem email verificado.

Ciclo de vida do canal

Código	Quando você vai ver
`channel_not_found`	O UUID do canal não existe (ou pertence a outro cliente).
`channel_access_denied`	Chave de API escopada por canal sendo usada contra um canal diferente.
`channel_unavailable`	O canal está em estado terminal (`logged_out`, `stopped_by_user`, `disabled_by_admin`, `error`, `failed`).
`channel_scoped_key`	A chave está escopada a um único canal, mas uma rota multi-canal foi chamada.
`invalid_lifecycle_transition`	Tentou dar `connect` num canal já conectado, etc.
`pair_code_unavailable`	O estado do canal não permite gerar um código de pareamento agora.
`pair_code_failed`	O upstream rejeitou a requisição do código de pareamento.
`no_qr`	QR ainda não pronto (o canal não inicializou), ou nenhum QR para este estado.
`not_disabled`	Tentou reativar um canal que não foi desativado por admin.
`concurrent_modification`	Duas escritas colidiram na mesma linha; refaça seu read-modify-write.

Plano / cota

Código	Quando você vai ver
`plan_channel_limit`	Limite de canais do plano atingido. Faça upgrade ou apague um canal existente.
`rate_limited`	Limite de requisições por chave esgotado. Respeite o `Retry-After`.
`worker_at_capacity`	Nenhum worker tem vaga livre agora — extremamente raro; refaça a retentativa.

Webhook + mídia

Código	Quando você vai ver
`webhook_endpoint_not_found`	O UUID do endpoint não existe.
`media_gone`	O token de mídia assinado é válido, mas os bytes saíram do cache por idade. Refaça o fetch da origem.

Genéricos

Código	Quando você vai ver
`invalid_request`	Corpo ou query falhou na validação Zod. `details` contém a lista de problemas.
`not_found`	404 genérico.
`bad_request`	400 genérico onde nenhum código mais específico se encaixa.
`no_op`	A mutação não teve efeito (já estava no estado-alvo).
`other`	Catch-all para erros do provedor upstream.
`internal_error`	Exceção não tratada no servidor. Somos alertados; `request_id` é a chave de rastreamento.

Boas práticas

Sempre registre o request_id. O suporte ao cliente usa ele para achar a requisição exata nos nossos traces.
Faça match no code, nunca na message. As mensagens são afinadas para legibilidade humana e mudam com o tempo.
Trate códigos desconhecidos como transitórios. Novos códigos são adicionados; assuma que dá pra retentar até a documentação ser atualizada.
Para 429, respeite o Retry-After em vez de chutar o backoff.