> ## Documentation Index > Fetch the complete documentation index at: https://docs.superlead.app/llms.txt > Use this file to discover all available pages before exploring further. # Tratamento de erros > O envelope de erro, o catálogo de códigos estáveis e como reagir a cada um. Toda falha retorna um envelope único, com um `code` **estável** — programe contra o código, nunca contra o texto de `message` (que pode mudar): ```json theme={null} { "error": { "code": "outside_24h_window", "message": "Free-form messages require the lead to have messaged you within the last 24 hours. Send an approved template instead.", "request_id": "req_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "upstream_code": 131047 } } ``` | Campo | Presença | Descrição | | --------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Sempre | Código estável do catálogo abaixo. | | `message` | Sempre | Explicação em inglês, sempre acionável. Pode mudar sem aviso. | | `request_id` | Sempre | Identificador da requisição. Informe ao suporte ao reportar um problema. O mesmo valor vem no header `X-Request-Id` de **toda** resposta (inclusive as de sucesso) — logue-o do seu lado. | | `upstream_code` | Em erros do WhatsApp | Código numérico original da Meta, para diagnóstico fino. | | `details` | Em `invalid_request` | Lista de `{ path, message }` apontando cada campo inválido do corpo. | ## Catálogo de códigos ### Requisição e autenticação | Código | HTTP | Quando acontece | O que fazer | | ---------------------- | ---- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `invalid_request` | 400 | Corpo ou parâmetros inválidos. | Corrija os campos apontados em `details`. | | `invalid_api_key` | 401 | Chave ausente, desconhecida ou revogada. | Confira o header `Authorization: Bearer sl_live_...`. | | `lead_not_found` | 404 | O destinatário não é um lead da sua empresa. | Confira a empresa da chave; crie o lead com `POST /v1/leads` se necessário. | | `message_not_found` | 404 | Nenhuma mensagem com esse id na sua empresa. | Use o `id` (`msg_...`) retornado no envio, não o `wamid`. | | `idempotency_conflict` | 409 | `Idempotency-Key` reutilizada com corpo diferente, ou requisição original ainda em andamento. | Use uma chave nova por operação; se em andamento, aguarde o `Retry-After`. | | `lead_already_exists` | 409 | Já existe lead com esse telefone na empresa. | Recupere com `GET /v1/leads?phone=...` e siga o fluxo normalmente. | ### Configuração da conta | Código | HTTP | Quando acontece | O que fazer | | -------------------------------- | ---- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | `funnel_not_configured` | 422 | A empresa não tem etapas de funil configuradas. | Configure o funil no painel antes de criar leads por API. | | `no_active_connection` | 422 | A empresa não tem conexão WhatsApp ativa. | Conecte um número no painel. | | `connection_expired` | 422 | A autorização da conexão WhatsApp expirou. | Reconecte o número no painel. | | `channel_capability_unsupported` | 422 | O tipo de conexão da empresa não suporta a operação (por exemplo, templates fora da Cloud API). | Verifique o tipo de conexão da empresa. | ### Envio (WhatsApp) | Código | HTTP | Quando acontece | O que fazer | | ------------------------- | ---- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `outside_24h_window` | 422 | Mensagem de formato livre fora da janela de 24 horas. | Envie um template aprovado. | | `template_not_found` | 422 | Nome ou idioma do template não bate com nenhum aprovado. | Confira com `GET /v1/templates`. | | `template_params_invalid` | 422 | Variáveis não batem com o template aprovado. | Confira quantidade, formato e idioma dos parâmetros. | | `recipient_unavailable` | 422 | O destinatário não pode receber a mensagem (número sem WhatsApp, por exemplo). | Valide o número com o lead. | | `media_unsupported` | 422 | O WhatsApp não conseguiu baixar ou processar a mídia do link. | Confira se o link é público e direto, o formato é suportado e o tamanho está no limite do tipo. Veja [Enviando mídia](/guias/envio-de-mensagens#enviando-midia). | | `message_blocked` | 422 | A Meta bloqueou a mensagem (limites de qualidade/spam). | Reduza o volume para esse destinatário e revise a qualidade do conteúdo. | | `rate_limit_exceeded` | 429 | Limite de requisições da **sua chave** excedido. | Aguarde o `Retry-After` e repita. Veja [Rate limits](/guias/rate-limits). | | `channel_rate_limit` | 429 | O **WhatsApp** está limitando o seu número. | Reduza o ritmo de envios e tente mais tarde. | ### Transitórios | Código | HTTP | Quando acontece | O que fazer | | ---------------- | ---- | ----------------------------------------- | ------------------------------------------------------------------- | | `channel_error` | 502 | Erro inesperado do provedor de mensagens. | Repita mais tarde, com `Idempotency-Key`. | | `internal_error` | 500 | Erro interno da Superlead. | Repita mais tarde; se persistir, informe o `request_id` ao suporte. | ## Falhas assíncronas Nem toda falha chega como erro HTTP: a Meta pode aceitar um envio (`201`) e falhá-lo segundos depois. Nesses casos, `GET /v1/messages/{id}` retorna `status: failed` com o campo `error` usando **os mesmos códigos deste catálogo**: ```json theme={null} { "status": "failed", "error": { "code": "outside_24h_window", "upstream_code": 131047 } } ``` Trate o `error.code` da consulta de status exatamente como trataria o `code` de uma resposta de erro síncrona. Para ser **notificado** da falha em vez de consultar, assine o evento `whatsapp.message.status` — veja [Webhooks](/guias/webhooks).