Pular para o conteúdo

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. A message é para pessoas e pode mudar.
  • Tente de novo só quando retryable for true, e com a mesma Idempotency-Key.
  • Informe o request_id ao suporte.

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

HTTPcodeQuandoO que fazerTentar de novo
400idempotency_key_requiredPOST, PATCH ou DELETE sem Idempotency-KeyEnvie o cabeçalhoNão
400invalid_cursorO cursor foi alterado ou é de outra listaUse o next_cursor da página anterior, sem mexerNão
400invalid_idempotency_keyChave com mais de 255 caracteres ou com caracteres fora do ASCII visívelUse um UUIDNão
400invalid_jsonO corpo não é JSONCorrija o pedidoNão
400invalid_requestCampo inválido ou faltando (details.fields)Corrija o pedidoNão
401api_key_revokedChave revogadaCrie outra chaveNão
401authentication_requiredSem Authorization: BearerEnvie a chaveNão
401invalid_api_keyChave malformada ou desconhecidaConfira a chave e o ambiente (pf_live_ em produção)Não
403insufficient_scopeA 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 deleCrie uma chave com o acessoNão
403plan_upgrade_requiredO plano do workspace não tem API (Gratuito, Try)Assine um plano pago; a mesma chave volta a funcionarNão
403workspace_archivedO workspace da chave foi arquivadoUse uma chave de outro workspaceNão
404lead_not_foundO lead_id não é lead deste workspaceConfira o idNão
404not_foundO recurso não existe neste workspaceConfira o idNão
404route_not_foundRota inexistenteConfira o caminho e a versãoNão
405method_not_allowedMétodo não aceito (cabeçalho Allow)Use o método certoNão
409idempotency_conflictA Idempotency-Key já foi usada com outro corpoGere uma chave nova para a nova operaçãoNão
409request_in_progressO pedido com essa chave ainda está executandoTente de novo em instantesÀs vezes (veja retryable)
409request_outcome_unknownO pedido com essa chave terminou sem resultado confirmadoConsulte o recurso antes de tentar com outra chaveNão
413payload_too_largeCorpo acima de 1 MB, ou arquivo acima de 16 MBReduza o tamanhoNão
415unsupported_media_typeCorpo sem Content-Type: application/jsonEnvie o cabeçalhoNão
429rate_limitedLimite atingido (Retry-After). Inclui os limites de teste, reenvio e cadastro de webhooks (details.bucket)Espere o tempo em Retry-AfterSim
500internal_errorErro inesperadoEm escrita, consulte o recurso antes de repetirSim
503temporarily_unavailableIndisponível no momentoTente de novo com a mesma Idempotency-KeySim

WhatsApp e arquivos

HTTPcodeQuandoO que fazerTentar de novo
402insufficient_creditsCréditos insuficientes para enviarRecarregue os créditosNão
404file_not_foundO media.file_id não é arquivo deste workspaceSuba de novo em POST /v1/filesNão
404sender_not_foundO from não é linha deste workspaceUse um id de GET /v1/whatsapp/sendersNão
404template_not_foundNão existe template com esse nomeConfira GET /v1/whatsapp/templatesNão
409contact_blockedContato encerrado, perdido, que saiu da empresa ou da própria empresaFale com o time no PreflowNão
409contact_pausedO contato está pausado até uma data (details.until)Tente depois da dataNão
409privacy_suppressedO contato pediu para não receber mensagensNão envieNão
409sender_unavailableA linha não está pronta (desconectada, pausada por qualidade ou em configuração)Use outra linha ou resolva a linha no PreflowNão
422file_not_uploadedOs bytes não foram enviados para a URL de uploadEnvie com PUT antes de mandar a mensagemNão
422invalid_phoneTelefone fora do E.164Use +5511999998888Não
422media_type_not_allowedTipo de arquivo não aceito (details.allowed)Converta o arquivoNão
422provider_rejectedO WhatsApp recusou a mensagem; nada foi cobradoConfira o número e o conteúdoNão
422send_refusedO Preflow recusou o envio por outro motivoFale com o suporte com o request_idNão
422sender_requiredSem from e sem linha padrão na chaveInforme from ou defina a linha padrãoNão
422template_not_approvedO template não está aprovado para o provedor da linhaAguarde a aprovaçãoNão
422template_unavailable_on_senderLinha do WhatsApp Business do celular não manda templateUse outra linhaNão
422template_variables_invalidFaltam variáveis (details.missing)Preencha todasNão
422whatsapp_window_closedTexto ou mídia fora da janela de 24 h (details.last_inbound_at)Use um template aprovadoNão

Leads, contas, cadências e reuniões

HTTPcodeQuandoO que fazerTentar de novo
403integration_actor_unavailableQuem criou a chave não pode mais inscrever leads no workspacePeça a um administrador uma chave novaNão
404cadence_not_foundA cadência não é deste workspace ou foi arquivadaUse um id de GET /v1/cadencesNão
404lead_mergedO lead foi mesclado em outro (details.merged_into)Passe a usar o lead de details.merged_intoNão
409cadence_born_cancelledTodas as etapas nasceriam canceladas (details.reason)Veja o motivo; nada foi inscritoNão
409cadence_enrollment_refusedOutra recusa da inscriçãoConsulte o lead e tente de novo com outra Idempotency-KeyNão
409cadence_no_tasks_createdNenhuma etapa pode ser criada (details.skipped_channels)Complete o contato do lead (e-mail, telefone) ou use outra cadênciaNão
409cadence_operator_unavailableA 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 contaNão
409external_id_in_progressOutro pedido está criando agora o lead deste external_idTente de novo em instantes; a resposta traz o lead criado pelo outro pedidoÀs vezes (veja retryable)
409lead_already_in_cadenceO lead já está nesta cadênciaNada a fazerNão
409lead_archivedO lead está arquivadoReabra o lead no PreflowNão
409lead_engagement_pausedO lead respondeu há pouco (details.until)Tente depois de details.untilNão
409lead_in_active_conversationO lead está numa conversa em andamentoTente depois que a conversa terminarNão
409lead_not_eligible_for_cadenceO 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_untilNão
422cadence_has_no_stepsA cadência não tem etapasUse outra cadênciaNão
422lead_suppressedO contato pediu para não ser contatado (privacidade). Também recusa a conversão de POST /v1/inbound-submissions, antes de qualquer registroNão crie o lead de novoNão

Conversões (POST /v1/inbound-submissions)

HTTPcodeQuandoO que fazerTentar de novo
409submission_id_conflictO submission_id já foi usado com outro conteúdoUse um submission_id novo para uma conversão novaNão
409submission_in_progressOutro pedido está registrando a mesma conversão agoraTente de novo em instantesÀs vezes (veja retryable)
422answers_invalidCom 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árioNão
422campaign_not_foundO campaign não é o slug de uma campanha deste workspace (ou está arquivada)Confira o slug da campanhaNão
422form_not_foundO form_id não é de um formulário publicado deste workspaceConfira o id do formulárioNão
422funnel_not_foundO funnel_id não é de um funil ativo deste workspaceUse um id de GET /v1/funnelsNão

Webhooks

HTTPcodeQuandoO que fazerTentar de novo
400invalid_webhook_urlURL que não é https://, com usuário e senha ou com mais de 2048 caracteresCorrija a URLNão
400unknown_event_typeEvento fora do catálogoConsulte GET /v1/event-typesNão
400webhook_url_not_allowedEndereço interno, privado, de metadados ou do PreflowUse uma URL pública do seu sistemaNão
409webhook_delivery_already_succeededReenvio de uma entrega que já deu certoNada a fazer: o evento já chegouNão
409webhook_delivery_in_progressA entrega está sendo enviada agoraTente de novo em instantesNão
409webhook_endpoint_limit_reachedO workspace já tem 10 endpointsExclua um endpointNão
409webhook_endpoint_not_activeTeste ou reenvio em endpoint desligado ou pausado pelo planoReligue o endpointNão
409webhook_rotation_in_progressO segredo foi girado há menos de 24 hEspere o anterior expirarNão