Erros
Todo erro tem o mesmo formato:
{ "error": { "code": "insufficient_scope", "message": "A chave não tem o escopo necessário para esta rota.", "request_id": "req_6f1c2b0e8a7d4c3b9e2f1a0d5c4b3a29", "retryable": false, "details": { "required_scope": "whatsapp:send" } }}- Decida pelo
code, que é estável. Amessageé para pessoas e pode mudar. - Tente de novo só quando
retryablefortrue, e com a mesmaIdempotency-Key. - Informe o
request_idao suporte.
Catálogo
Seção intitulada “Catálogo”Esta tabela é gerada do código da API a cada publicação, então todo código que a API pode devolver está aqui.
Gerais
| HTTP | code | Quando | O que fazer | Tentar de novo |
|---|---|---|---|---|
| 400 | idempotency_key_required | POST, PATCH ou DELETE sem Idempotency-Key | Envie o cabeçalho | Não |
| 400 | invalid_cursor | O cursor foi alterado ou é de outra lista | Use o next_cursor da página anterior, sem mexer | Não |
| 400 | invalid_idempotency_key | Chave com mais de 255 caracteres ou com caracteres fora do ASCII visível | Use um UUID | Não |
| 400 | invalid_json | O corpo não é JSON | Corrija o pedido | Não |
| 400 | invalid_request | Campo inválido ou faltando (details.fields) | Corrija o pedido | Não |
| 401 | api_key_revoked | Chave revogada | Crie outra chave | Não |
| 401 | authentication_required | Sem Authorization: Bearer | Envie a chave | Não |
| 401 | invalid_api_key | Chave malformada ou desconhecida | Confira a chave e o ambiente (pf_live_ em produção) | Não |
| 403 | insufficient_scope | A chave não tem o acesso da rota (details.required_scope). Em webhooks, assinar ou ler um tipo de evento exige também o acesso de leitura do módulo dele | Crie uma chave com o acesso | Não |
| 403 | plan_upgrade_required | O plano do workspace não tem API (Gratuito, Try) | Assine um plano pago; a mesma chave volta a funcionar | Não |
| 403 | workspace_archived | O workspace da chave foi arquivado | Use uma chave de outro workspace | Não |
| 404 | lead_not_found | O lead_id não é lead deste workspace | Confira o id | Não |
| 404 | not_found | O recurso não existe neste workspace | Confira o id | Não |
| 404 | route_not_found | Rota inexistente | Confira o caminho e a versão | Não |
| 405 | method_not_allowed | Método não aceito (cabeçalho Allow) | Use o método certo | Não |
| 409 | idempotency_conflict | A Idempotency-Key já foi usada com outro corpo | Gere uma chave nova para a nova operação | Não |
| 409 | request_in_progress | O pedido com essa chave ainda está executando | Tente de novo em instantes | Às vezes (veja retryable) |
| 409 | request_outcome_unknown | O pedido com essa chave terminou sem resultado confirmado | Consulte o recurso antes de tentar com outra chave | Não |
| 413 | payload_too_large | Corpo acima de 1 MB, ou arquivo acima de 16 MB | Reduza o tamanho | Não |
| 415 | unsupported_media_type | Corpo sem Content-Type: application/json | Envie o cabeçalho | Não |
| 429 | rate_limited | Limite atingido (Retry-After). Inclui os limites de teste, reenvio e cadastro de webhooks (details.bucket) | Espere o tempo em Retry-After | Sim |
| 500 | internal_error | Erro inesperado | Em escrita, consulte o recurso antes de repetir | Sim |
| 503 | temporarily_unavailable | Indisponível no momento | Tente de novo com a mesma Idempotency-Key | Sim |
WhatsApp e arquivos
| HTTP | code | Quando | O que fazer | Tentar de novo |
|---|---|---|---|---|
| 402 | insufficient_credits | Créditos insuficientes para enviar | Recarregue os créditos | Não |
| 404 | file_not_found | O media.file_id não é arquivo deste workspace | Suba de novo em POST /v1/files | Não |
| 404 | sender_not_found | O from não é linha deste workspace | Use um id de GET /v1/whatsapp/senders | Não |
| 404 | template_not_found | Não existe template com esse nome | Confira GET /v1/whatsapp/templates | Não |
| 409 | contact_blocked | Contato encerrado, perdido, que saiu da empresa ou da própria empresa | Fale com o time no Preflow | Não |
| 409 | contact_paused | O contato está pausado até uma data (details.until) | Tente depois da data | Não |
| 409 | privacy_suppressed | O contato pediu para não receber mensagens | Não envie | Não |
| 409 | sender_unavailable | A linha não está pronta (desconectada, pausada por qualidade ou em configuração) | Use outra linha ou resolva a linha no Preflow | Não |
| 422 | file_not_uploaded | Os bytes não foram enviados para a URL de upload | Envie com PUT antes de mandar a mensagem | Não |
| 422 | invalid_phone | Telefone fora do E.164 | Use +5511999998888 | Não |
| 422 | media_type_not_allowed | Tipo de arquivo não aceito (details.allowed) | Converta o arquivo | Não |
| 422 | provider_rejected | O WhatsApp recusou a mensagem; nada foi cobrado | Confira o número e o conteúdo | Não |
| 422 | send_refused | O Preflow recusou o envio por outro motivo | Fale com o suporte com o request_id | Não |
| 422 | sender_required | Sem from e sem linha padrão na chave | Informe from ou defina a linha padrão | Não |
| 422 | template_not_approved | O template não está aprovado para o provedor da linha | Aguarde a aprovação | Não |
| 422 | template_unavailable_on_sender | Linha do WhatsApp Business do celular não manda template | Use outra linha | Não |
| 422 | template_variables_invalid | Faltam variáveis (details.missing) | Preencha todas | Não |
| 422 | whatsapp_window_closed | Texto ou mídia fora da janela de 24 h (details.last_inbound_at) | Use um template aprovado | Não |
Leads, contas, cadências e reuniões
| HTTP | code | Quando | O que fazer | Tentar de novo |
|---|---|---|---|---|
| 403 | integration_actor_unavailable | Quem criou a chave não pode mais inscrever leads no workspace | Peça a um administrador uma chave nova | Não |
| 404 | cadence_not_found | A cadência não é deste workspace ou foi arquivada | Use um id de GET /v1/cadences | Não |
| 404 | lead_merged | O lead foi mesclado em outro (details.merged_into) | Passe a usar o lead de details.merged_into | Não |
| 409 | cadence_born_cancelled | Todas as etapas nasceriam canceladas (details.reason) | Veja o motivo; nada foi inscrito | Não |
| 409 | cadence_enrollment_refused | Outra recusa da inscrição | Consulte o lead e tente de novo com outra Idempotency-Key | Não |
| 409 | cadence_no_tasks_created | Nenhuma etapa pode ser criada (details.skipped_channels) | Complete o contato do lead (e-mail, telefone) ou use outra cadência | Não |
| 409 | cadence_operator_unavailable | A conta do lead não tem quem execute a cadência (details.reason: missing_cadence_operator, cadence_operator_conflicts_with_account_owner, cadence_operator_not_eligible, human_account_owner_not_eligible ou ai_cadence_requires_human_account_owner) | Defina o dono de pré-vendas da conta | Não |
| 409 | external_id_in_progress | Outro pedido está criando agora o lead deste external_id | Tente de novo em instantes; a resposta traz o lead criado pelo outro pedido | Às vezes (veja retryable) |
| 409 | lead_already_in_cadence | O lead já está nesta cadência | Nada a fazer | Não |
| 409 | lead_archived | O lead está arquivado | Reabra o lead no Preflow | Não |
| 409 | lead_engagement_paused | O lead respondeu há pouco (details.until) | Tente depois de details.until | Não |
| 409 | lead_in_active_conversation | O lead está numa conversa em andamento | Tente depois que a conversa terminar | Não |
| 409 | lead_not_eligible_for_cadence | O lead não pode entrar em cadência agora (details.reason: lead_do_not_contact_until, lead_passed_meeting_stage, lost_cooldown, lost_reprospect_not_eligible, status_not_appendable, meeting_reprospect_not_eligible, not_eligible) | Veja o motivo; lost_cooldown traz details.cooldown_until | Não |
| 422 | cadence_has_no_steps | A cadência não tem etapas | Use outra cadência | Não |
| 422 | lead_suppressed | O contato pediu para não ser contatado (privacidade). Também recusa a conversão de POST /v1/inbound-submissions, antes de qualquer registro | Não crie o lead de novo | Não |
Conversões (POST /v1/inbound-submissions)
| HTTP | code | Quando | O que fazer | Tentar de novo |
|---|---|---|---|---|
| 409 | submission_id_conflict | O submission_id já foi usado com outro conteúdo | Use um submission_id novo para uma conversão nova | Não |
| 409 | submission_in_progress | Outro pedido está registrando a mesma conversão agora | Tente de novo em instantes | Às vezes (veja retryable) |
| 422 | answers_invalid | Com form_id: resposta para campo que não existe, fora das opções ou campo obrigatório vazio (details.fields) | Ajuste as respostas ao formulário | Não |
| 422 | campaign_not_found | O campaign não é o slug de uma campanha deste workspace (ou está arquivada) | Confira o slug da campanha | Não |
| 422 | form_not_found | O form_id não é de um formulário publicado deste workspace | Confira o id do formulário | Não |
| 422 | funnel_not_found | O funnel_id não é de um funil ativo deste workspace | Use um id de GET /v1/funnels | Não |
Webhooks
| HTTP | code | Quando | O que fazer | Tentar de novo |
|---|---|---|---|---|
| 400 | invalid_webhook_url | URL que não é https://, com usuário e senha ou com mais de 2048 caracteres | Corrija a URL | Não |
| 400 | unknown_event_type | Evento fora do catálogo | Consulte GET /v1/event-types | Não |
| 400 | webhook_url_not_allowed | Endereço interno, privado, de metadados ou do Preflow | Use uma URL pública do seu sistema | Não |
| 409 | webhook_delivery_already_succeeded | Reenvio de uma entrega que já deu certo | Nada a fazer: o evento já chegou | Não |
| 409 | webhook_delivery_in_progress | A entrega está sendo enviada agora | Tente de novo em instantes | Não |
| 409 | webhook_endpoint_limit_reached | O workspace já tem 10 endpoints | Exclua um endpoint | Não |
| 409 | webhook_endpoint_not_active | Teste ou reenvio em endpoint desligado ou pausado pelo plano | Religue o endpoint | Não |
| 409 | webhook_rotation_in_progress | O segredo foi girado há menos de 24 h | Espere o anterior expirar | Não |