Feito para pessoas e agentes de IA
Cada página aqui é legível por humanos — guias por tarefa e conceitos — apoiada por um contrato OpenAPI completo. A mesma referência vem em um cookbook aberto que você clona no seu projeto em segundos.
Trabalhando com um agente de IA? Clone o cookbook
RecomendadoAponte seu agente para o PLAYBOOK.md — um guia passo a passo para a referência da API e exemplos prontos, para ele ler só o necessário em cada etapa.
Ver o cookbook no GitHubPrefere colar como contexto? Baixe a documentação completa em um único arquivo Markdown, ou pegue só a spec.
Todas as requisições à API exigem uma chave de API no header X-API-Key.
Crie uma chave na página API Keys do portal. A chave completa é exibida apenas uma vez — guarde-a com segurança. Chaves perdidas não podem ser recuperadas; revogue e crie uma nova.
curl https://fiwano.com/api/v1/channels \
-H "X-API-Key: YOUR_API_KEY"
Todas as chaves começam com mip_live_. As chaves são armazenadas como hash do nosso lado.
Toda resposta de erro tem um campo detail. A maioria dos erros de domínio usa uma descrição legível:
{ "detail": "Human-readable error description" }
A validação de esquema (422) usa uma lista de erros de campo. Alguns erros de
validação de domínio usam um objeto detail estruturado com um campo code — por
exemplo text_too_long ao enviar um texto longo demais, ou recipient_equals_sender
(400) quando um envio de WhatsApp é endereçado ao próprio número do canal. Os
formatos por endpoint estão na Referência da API.
| Código | Significado | O que fazer |
|---|---|---|
200 |
Sucesso | — |
201 |
Criado | — |
400 |
Requisição inválida | Verifique o campo detail |
401 |
Não autorizado | Verifique seu header X-API-Key |
402 |
Pagamento necessário | Período de teste encerrado ou assinatura inativa — veja Assinaturas e Cobrança |
404 |
Não encontrado | O recurso não existe ou pertence a outra conta |
422 |
Erro de validação | Verifique campos obrigatórios, tipos e restrições de campo em detail |
429 |
Limite de taxa excedido | Reduza o ritmo e tente novamente após Retry-After — veja limites de taxa |
502 |
Erro da API da Meta | Falha no upstream. Verifique detail. Tentar novamente pode ajudar. |
503 |
Sobrecarregado temporariamente | Descarte de carga transitório. Tente novamente após Retry-After. |
Os três endpoints de envio respondem 200 mesmo quando o envio falha — o
resultado está em success, status e error_code. Veja
Entrega e novas tentativas.
error_code é o código de erro da Meta, repassado sem alteração. Ele só está
presente quando a falha veio da Meta; uma rejeição pelo próprio Fiwano usa um
código de status HTTP da tabela acima. error sempre traz uma descrição
legível e, em envios de mídia, uma dica sobre a causa provável.
error_code |
Significado | Nova tentativa pelo Fiwano | O que fazer |
|---|---|---|---|
10, 200 |
Permissão negada para esta ação | não | Reconecte o canal |
100 |
Parâmetro inválido — a Meta reutiliza este código para causas distintas, incluindo arquivo acima do limite de tamanho | não | Leia error para a causa específica; verifique media_url, media_type, formato do destinatário e o tamanho do arquivo |
190 |
Token de acesso expirado ou revogado | não | Reconecte o canal |
368 |
Conta temporariamente bloqueada por violação de políticas | não | Resolva no Meta Business Manager |
803 |
Objeto não existe ou está indisponível | não | Verifique o identificador do destinatário |
131008 |
Parâmetro obrigatório ausente | não | Corrija o payload |
131009 |
Valor de parâmetro inválido para este canal | não | Corrija o payload |
131026 |
Destinatário não acessível nesta plataforma | não | Verifique o destinatário |
131047, 131057 |
Janela de reengajamento de 24h fechada | não | Envie um modelo aprovado do WhatsApp — veja janelas de mensagens |
131051 |
Tipo de mensagem não suportado neste canal | não | Verifique as capacidades do canal |
131052 |
A Meta não conseguiu baixar a media_url |
não | Verifique se a URL retorna 200, se o Content-Type corresponde ao media_type e se a assinatura não expirou |
131053 |
A Meta não conseguiu processar a mídia | sim | Geralmente transitório; verifique formato e tamanho se persistir |
131056 |
Limite de taxa entre este remetente e destinatário | sim | Reduza o ritmo de mensagens para esse destinatário |
Códigos fora desta tabela são repassados como a Meta os retorna. Tudo que não for reconhecido como permanente é tratado como transitório e repetido.
Raramente, a Meta aceita um envio mas sua resposta nunca chega ao Fiwano — uma conexão perdida ou um timeout durante a resposta. A mensagem pode ou não ter sido entregue, e a Meta não oferece forma de consultar isso depois.
O Fiwano não repete esses envios: uma nova tentativa automática correria o
risco de entregar a mesma mensagem duas vezes. A resposta é success: false,
status: "failed", com um error informando que o resultado não foi
confirmado e sem error_code.
Verifique a conversa antes de reenviar. A mesma cautela vale se o seu próprio cliente HTTP atingir o timeout — veja Tempo de resposta.
Documentação da API Fiwano