Formato da resposta
{ "message_uuid": "...", "wamid": "..." }
{
"code": "WINDOW_CLOSED",
"message": "The 24-hour messaging window is closed. Send an approved template to reopen it."
}
{ code, message } — ambos os campos são garantidos.
Faça
switch sobre code: é estável e faz parte do contrato. O message
é texto humano de ajuda e pode ser refinado entre versões da API sem aviso.
As mensagens são entregues em inglês (padrão de indústria, mesmo padrão que
Stripe, GitHub ou Linear). Se precisar exibi-las traduzidas para o usuário
final, mapeie-as no seu cliente por code.Famílias de status
| HTTP | Significado | Repetir? |
|---|---|---|
2xx | Sucesso — 200 leitura, 201 criação, 202 aceito (async), 207 multi-status. | — |
4xx | Erro da requisição — auth, validação ou recurso inexistente. | Não, corrija antes. |
429 | Rate limit excedido. | Sim, após o Retry-After. |
5xx | Erro do servidor. | Sim, com backoff. |
Catálogo de códigos
O status HTTP de cada código é típico: o endpoint específico pode retornar
outro status se o contexto justificar. O authoritative por endpoint vive na
Referência da API. A tabela aqui é referência geral, não contrato
vinculante por endpoint.Os códigos de ambiguidade de resolução de conversa (
PHONE_NUMBER_AMBIGUOUS,
USERNAME_AMBIGUOUS) podem aparecer em qualquer endpoint que aceite uma
referência conversation por phone/username, mesmo que sua Referência da
API liste outros códigos 409.Auth e tenant
| Code | HTTP | Descrição |
|---|---|---|
INVALID_API_TOKEN | 401 | O token não existe ou foi revogado. Gere um novo em Settings → API Token. |
TOKEN_BUSINESS_MISMATCH | 403 | O token não pertence ao slug do negócio na URL. Verifique que ambos se refiram ao mesmo negócio. |
Rate limit
| Code | HTTP | Descrição |
|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Você excedeu o bucket de 60 req/min. Espere os segundos do header Retry-After. Ver Rate limits. |
Validação
| Code | HTTP | Descrição |
|---|---|---|
INVALID_REQUEST | 400 | O body não passou na validação de schema (campo faltante, tipo incorreto, valor fora do intervalo). |
INVALID_CURSOR | 400 | O cursor de paginação é inválido ou expirou. Reinicie a listagem sem cursor. |
BATCH_LIMIT_EXCEEDED | 400 | O grupo de ações excede o máximo permitido em uma única requisição. O message carrega o cap real. |
Conversa, contato e canal
| Code | HTTP | Descrição |
|---|---|---|
CONVERSATION_NOT_FOUND | 404 | O identificador de conversation (uuid, whatsapp_user_id, username ou phone) não resolve para nenhuma conversa do negócio. |
CONTACT_NOT_FOUND | 404 | O identificador de contato não resolve para nenhum do negócio. |
PHONE_NUMBER_AMBIGUOUS | 409 | Vários contatos compartilham esse telefone (números reciclados / identidades separadas). Identifique a conversa por whatsapp_user_id ou uuid. |
USERNAME_AMBIGUOUS | 409 | Vários contatos compartilham esse username. Identifique a conversa por whatsapp_user_id ou uuid. |
CHANNEL_NOT_CONFIGURED | 422 | A conversa não tem um canal de WhatsApp configurado. Conecte um no dashboard antes de enviar. |
TESTER_CONVERSATION_NOT_WRITABLE | 422 | Conversas tester não aceitam envios reais ao WhatsApp. Use uma real, ou limite a ação a tags/notas/mailbox. |
TRANSCRIPTION_REQUIRED_TO_RESOLVE | 422 | POST /conversation/resolve: a conversa tem mídia recebida com transcrição pendente. Complete a transcrição manual pelo dashboard e tente novamente. |
Tags
| Code | HTTP | Descrição |
|---|---|---|
TAG_NOT_FOUND | 404 | A tag não existe para este negócio. |
TAG_ALREADY_ASSIGNED | 409 | A tag já está atribuída a esta conversa. |
TAG_NOT_ASSIGNED | 404 | A tag não está atribuída, então não pode ser removida. |
TAG_AMBIGUOUS | 409 | Há várias tags com esse nome. Use tag_uuid para desambiguar. |
TAG_BUSINESS_MISMATCH | 400 | A tag pertence a outro negócio. |
CANNOT_ASSIGN_DEFAULT_TAG | 422 | A tag é gerenciada pelo sistema (administrada pelo backend, ex.: a de conversão pendente) e não pode ser atribuída pela API. |
CANNOT_REMOVE_DEFAULT_TAG | 422 | A tag é gerenciada pelo sistema (administrada pelo backend, ex.: a de conversão pendente) e não pode ser removida pela API. |
Mailboxes e categorias
| Code | HTTP | Descrição |
|---|---|---|
CATEGORY_NOT_FOUND | 404 | A categoria de mailbox não existe para este negócio. |
CATEGORY_BUSINESS_MISMATCH | 403 | A categoria pertence a outro negócio. |
AMBIGUOUS_CATEGORY | 409 | Há várias categorias com esse nome. Use category_uuid para desambiguar. |
MAILBOX_NOT_FOUND | 404 | O mailbox não existe para este negócio. |
MAILBOX_ALREADY_ASSIGNED | 409 | A conversa já está nesse mailbox. |
AMBIGUOUS_MAILBOX | 409 | Há vários mailboxes com esse nome. Use mailbox_uuid para desambiguar. |
NO_MAILBOXES_IN_CATEGORY | 422 | A categoria não tem mailboxes configurados. Adicione pelo menos um no dashboard. |
Guards de pré-condição
| Code | HTTP | Descrição |
|---|---|---|
WINDOW_CLOSED | 422 | A janela de 24h está fechada. Envie um template aprovado para reabri-la. |
WALLET_BLOCKED | 402 | A wallet de tokens do modelo de AI requerido está vazia ou bloqueada. Recarregue para continuar. |
VISION_WALLET_BLOCKED | 402 | A wallet de vision tokens está vazia. O processamento de visão requer recarga. |
VISION_BLOCKED | 402 | O pipeline de visão da thread está bloqueado. Resolva a mídia pendente no dashboard antes de tentar novamente. |
NO_AI_EMPLOYEE_ASSIGNED | 422 | A conversa não tem um funcionário AI atribuído. Atribua um antes de executar a ação. |
Coerência owner ↔ executor (schedules)
| Code | HTTP | Descrição |
|---|---|---|
OWNER_MISMATCH | 422 | O executor do scheduled message não coincide com o owner atual da conversa. Reatribua ou cancele o schedule primeiro. |
Funcionários AI e execução
| Code | HTTP | Descrição |
|---|---|---|
AI_EMPLOYEE_NOT_FOUND | 404 | O funcionário AI não existe para este negócio. |
AMBIGUOUS_AI_EMPLOYEE | 409 | Há vários funcionários com esse nome. Use ai_employee_uuid para desambiguar. |
AI_EMPLOYEE_ALREADY_ASSIGNED | 409 | Esse funcionário AI já está atribuído à conversa. |
INVALID_ASSIGNEE_FOR_RUN_AI | 409 | A conversa é human-owned e nenhum ai_employee foi especificado. Passe um ou reatribua um AI primeiro. |
AI_EXECUTION_FAILED | 500 | A execução do AI falhou inesperadamente. Tente novamente; se persistir, verifique o dashboard do funcionário. |
ACTIONS_DEPTH_EXCEEDED | 422 | Ações de AI encadeadas excedem a profundidade máxima permitida em uma requisição. |
Scheduled message action
| Code | HTTP | Descrição |
|---|---|---|
SCHEDULED_MESSAGE_ACTION_REQUIRED | 422 | Há um scheduled message ativo na conversa. Especifique scheduled_message_action (reassign ou cancel). |
SCHEDULED_MESSAGE_ACTION_INVALID | 400 | O valor de scheduled_message_action é inválido. Deve ser reassign ou cancel. |
Uploads
| Code | HTTP | Descrição |
|---|---|---|
INVALID_FILE_TYPE | 400 | O tipo de arquivo não é permitido. Veja a documentação para a lista de MIME types aceitos. |
FILE_TOO_LARGE | 400 | O arquivo excede o tamanho máximo para sua categoria. |
STORAGE_QUOTA_EXCEEDED | 413 | O negócio atingiu sua cota de storage. Libere espaço ou faça upgrade do plano. |
STORAGE_QUOTA_CLEANUP_INSUFFICIENT | 507 | O storage está cheio e a limpeza automática não conseguiu liberar espaço suficiente para este upload. Libere espaço ou faça upgrade do plano. |
FILE_NOT_FOUND | 404 | Não existe arquivo com esse file_uuid para este negócio. |
FILE_NOT_UPLOADED | 422 | O arquivo foi registrado mas o upload nunca foi confirmado. Re-suba antes de referenciá-lo. |
SIZE_MISMATCH | 422 | O tamanho real do arquivo subido não coincide com o declarado em request-upload. |
MIME_MISMATCH | 422 | O MIME type real não coincide com o declarado. Re-suba com o Content-Type correto. |
UPLOAD_FAILED | 500 | O upload não pôde ser concluído por um erro de storage. Tente novamente. |
Mensagens
| Code | HTTP | Descrição |
|---|---|---|
PREPARE_FAILED | 500 | A mensagem não pôde ser preparada (erro de DB ou upstream). Tente novamente. |
SEND_FAILED | 502 | O envio ao WhatsApp falhou. Verifique a saúde do canal e tente novamente. |
BSUID_SEND_DISABLED | 409 | O contato não tem telefone e o envio pela sua identidade BSUID (business-scoped user ID) está desabilitado para este negócio. Use um contato com telefone ou habilite o envio por BSUID. |
Quick replies e templates
| Code | HTTP | Descrição |
|---|---|---|
QUICK_REPLY_NOT_FOUND | 404 | A quick reply não existe para este negócio. |
QUICK_REPLY_AMBIGUOUS | 409 | Há várias quick replies com esse nome. Use quick_reply_uuid para desambiguar. |
QUICK_REPLY_EMPTY | 422 | A quick reply não tem ações configuradas. Adicione pelo menos uma no dashboard. |
TEMPLATE_NOT_FOUND | 404 | O template não existe para este negócio. |
TEMPLATE_NOT_APPROVED | 422 | O template não está aprovado pela Meta. Aprovação é requisito para envio. |
AUTH_TEMPLATE_REQUIRES_PHONE | 409 | Não é possível enviar um template de autenticação a um contato sem telefone: a Meta exige o número. Envie a um contato com telefone. |
TEMPLATE_AMBIGUOUS | 409 | Há vários templates com esse nome. Especifique language para desambiguar. |
TEMPLATE_VARIABLES_INVALID | 422 | As variáveis do body não coincidem com o template (contagem incorreta, índice faltante ou valor vazio). |
TEMPLATE_HEADER_MISMATCH | 400 | O tipo de header não coincide com o que o template declara (ex: template espera imagem e você enviou texto). |
TEMPLATE_FAKE_REQUIRES_TESTER_CONVERSATION | 422 | O template é do módulo Tester (fake) e só pode ser enviado a conversas tester. |
Operações genéricas
| Code | HTTP | Descrição |
|---|---|---|
FETCH_FAILED | 500 | Não foi possível ler os dados necessários para concluir a requisição. Tente novamente. |
UPDATE_FAILED | 500 | A alteração não pôde ser aplicada (erro de DB). Tente novamente. |
UNKNOWN_ERROR | 500 | Erro inesperado. Contate o suporte se persistir. |