CRPRO HubEntrar no painel

Erros

Todo erro desta API vem no mesmo formato, com o mesmo conjunto de campos, seja qual for o endpoint ou a causa. Vale a pena tratar o código de erro programaticamente em vez da mensagem: a mensagem é para leitura humana e pode mudar sem aviso.

O envelope de erro

Toda resposta de erro vem envelopada em {"error": {...}}, nunca junto com data. O campo details traz contexto extra específico do código — por exemplo, o tempo de espera de um 429 — e pode vir vazio.

Resposta de erro
{
  "error": {
    "code": "INVALID_BODY",
    "message": "Corpo da requisição inválido.",
    "details": {}
  }
}

x-request-id

Toda resposta, de sucesso ou erro, traz o header x-request-id. Cite esse valor ao abrir um chamado de suporte: ele é o jeito mais rápido de localizar a requisição exata nos logs internos, sem precisar reconstruir o horário e os parâmetros da chamada.

Códigos de erro

Agrupados por status HTTP, na ordem em que a API os devolve com mais frequência dentro do grupo.

400

CódigoQuando aconteceComo resolver
INVALID_JSONO corpo da requisição não é um JSON válido.Envie JSON bem formado e o header content-type: application/json.
INVALID_PINO PIN enviado para registrar o número não confere com a verificação em duas etapas dele (erro #133005 da Meta).Confira o PIN e tente de novo; details.attempts_remaining diz quantas tentativas restam antes de o Hub indicar a recuperação.
PIN_REQUIRED_RECOVERYTrês PINs recusados em uma hora: a verificação em duas etapas do número já está ativa com um PIN que não é o informado.Redefina o PIN no WhatsApp Manager (Configurações da conta → Verificação em duas etapas) e registre de novo, ou refaça a conexão pelo link.
INVALID_PROFILEOs dados de perfil do número não passaram na validação da Meta.Confira tamanho e formato de cada campo do perfil antes de reenviar.
INVALID_TEMPLATE_NAMEO nome do template não segue o formato exigido pela Meta.Use apenas letras minúsculas, números e underscore, sem espaços.
INVALID_TEMPLATE_IDO hsm_id enviado na exclusão de template não tem forma de id da Meta.Use o hsm_id que veio na listagem de templates, só dígitos. Ele é o que limita a exclusão a um idioma: sem hsm_id, a Meta apaga todas as versões daquele nome.
INVALID_FIELD_MODIFIERUm campo pedido na leitura do WABA veio com modificador fora do formato aceito.Use apenas start, end, granularity, dimensions e metric_types, no formato .start(1717200000).end(1719791999).
IDEMPOTENCY_KEY_INVALIDO header Idempotency-Key veio com um formato que a API não aceita.Envie um valor não vazio, com até 255 caracteres, sem espaços nas pontas.
IDEMPOTENCY_KEY_REQUIREDA requisição precisa do header Idempotency-Key e ele não foi enviado.Inclua o header Idempotency-Key com um valor novo (um UUID serve bem) a cada operação distinta.
INVALID_API_KEYOs dados enviados para criar ou atualizar uma chave de API não passaram na validação.Confira nome, escopos e data de expiração da chave contra o schema documentado no recurso.
INVALID_BODYO corpo da requisição não é um JSON válido ou não bate com o schema esperado pelo endpoint.Valide o corpo contra o schema do endpoint antes de enviar e confirme o header Content-Type: application/json.
INVALID_PINA conclusão da conexão veio com um pin que não tem exatamente 6 dígitos.Envie o campo pin com os 6 dígitos informados pelo cliente, ou não envie o campo. O PIN não é mais obrigatório no início: o Hub só o pede quando o número ainda não está registrado na Cloud API, e nesse caso a resposta anterior traz pin_required: true. Se o número já tinha verificação em duas etapas ativa, precisa ser o PIN original — divergir devolve pin_incorreto (erro #133005 da Meta) e a sessão aceita uma nova tentativa.
INVALID_CALLO corpo enviado a POST /meta/{phone_number_id}/calls nao passou na validacao: messaging_product precisa ser "whatsapp", call_id precisa ser uma string nao vazia de ate 256 caracteres e action so aceita reject ou terminate.Envie exatamente {"messaging_product":"whatsapp","call_id":"wacid....","action":"reject"}. As acoes accept e pre_accept exigem sessao SDP e nao passam pela fachada /meta; qualquer campo alem desses tres e descartado.
COMANDO_DESCONHECIDOO identificador do comando administrativo enviado não existe no catálogo de comandos.Confira o id do comando contra a lista de comandos disponíveis e reenvie com um comando válido.
MOTIVO_OBRIGATORIOUm comando destrutivo foi executado sem o campo motivo preenchido.Preencha o campo motivo com uma explicação legível sobre o motivo da ação destrutiva.
PARAMETROS_INVALIDOSOs parâmetros enviados para o comando não correspondem ao schema esperado.Valide os parâmetros contra o schema do comando antes de reenviar.
INVALID_CHANNELOs dados enviados para criar ou atualizar um canal não passaram na validação.Revise os campos do canal (nome, número, configuração) contra o schema do recurso Canais.
INVALID_CURSORO parâmetro cursor de uma listagem paginada veio corrompido ou adulterado.Use sempre o valor de cursor devolvido pela própria API na resposta anterior, sem editá-lo.
INVALID_EXPIRATIONA data de expiração enviada para uma chave de API não está no futuro.Envie expires_at como uma data ISO 8601 posterior ao momento atual, ou omita para não expirar.
INVALID_MEDIAO arquivo de mídia enviado está ausente, tem um tipo não suportado ou excede o tamanho máximo do tipo.Confira o tipo MIME e o tamanho do arquivo contra os limites da página de Limites antes de enviar.
INVALID_MESSAGEO corpo da mensagem não corresponde a nenhum tipo de mensagem WhatsApp suportado.Revise o campo type e os campos específicos do tipo contra o schema de POST .../messages.
INVALID_QUERYOs parâmetros de consulta (query string) de uma listagem não passaram na validação.Confira nomes, tipos e valores permitidos dos parâmetros de consulta do endpoint.
INVALID_SCOPEA criação de uma chave de API pediu um ou mais escopos que não existem.Use apenas escopos da lista documentada na tabela de escopo por papel, em Autenticação.
INVALID_TEMPLATEO corpo de envio de template não bate com o schema exigido pela Meta para templates aprovados.Confira o nome, idioma e os parâmetros de componentes do template contra o que foi aprovado na Meta.
INVALID_WEBHOOKA configuração enviada para criar ou atualizar um webhook (url, eventos, modo de payload) é inválida.Revise url, event_types e payload_mode contra o schema do recurso Webhooks.
INVALID_WEBHOOK_EVENTUm evento interno tentou ser enfileirado com um tipo que não está em WEBHOOK_EVENT_TYPES, ou com dados incompletos.Isto normalmente não é causado pelo integrador — se aparecer, cite o x-request-id ao abrir suporte.
INVALID_WEBHOOK_PAYLOADO payload de um evento de webhook não pôde ser serializado em JSON.Isto normalmente não é causado pelo integrador — se aparecer, cite o x-request-id ao abrir suporte.
WEBHOOK_DNS_FAILEDA URL do webhook não pôde ser resolvida por DNS no momento do cadastro.Confirme que o domínio do endpoint resolve publicamente antes de cadastrar o webhook.
WEBHOOK_URL_NOT_ALLOWEDA URL do webhook usa um esquema, host ou faixa de IP que a política de destino bloqueia.Use HTTPS, um host público e evite redes internas — veja a seção de bloqueios em Webhooks.

401

CódigoQuando aconteceComo resolver
UNAUTHENTICATEDA rota exige uma sessão de administrador da plataforma e nenhuma sessão válida foi enviada.Autentique-se no painel administrativo antes de chamar a rota.

402

CódigoQuando aconteceComo resolver
ACTIVE_SUBSCRIPTION_REQUIREDA organização não tem uma assinatura paga em estado ativo.Contrate ou reative um plano em /painel/assinatura antes de repetir a operação.
SUBSCRIPTION_REQUIREDA operação (enviar mensagem, criar webhook) exige assinatura e a organização está sem uma.Contrate um plano em /painel/assinatura; o envio e a criação de webhook voltam a funcionar assim que a assinatura fica ativa.

403

CódigoQuando aconteceComo resolver
FORBIDDENA sessão autenticada não tem permissão de administrador da plataforma para a rota.Esta rota é restrita à equipe interna — não há ação possível do lado do integrador.
OWNER_REQUIREDA operação de cobrança (contratar plano ou adicional) foi chamada por alguém que não é o proprietário da organização.Peça para o proprietário da organização realizar a operação, ou delegue o papel de owner a quem for executar.
PLAN_QUOTA_EXCEEDEDA organização atingiu o limite de canais ou de webhooks do plano contratado.Remova um recurso existente ou faça upgrade do plano em /painel/assinatura.
SESSION_REQUIREDUm endpoint de gestão de chaves de API foi chamado com uma chave de API em vez de uma sessão do painel.Gerencie chaves de API autenticado por sessão do painel; uma chave de API não pode criar ou revogar outras chaves.

404

CódigoQuando aconteceComo resolver
META_RESOURCE_NOT_FOUNDO recurso pedido não existe na Meta ou não pertence a este canal.Confirme o identificador e se ele foi criado sob o mesmo número.
NOT_FOUNDO identificador do recurso na URL não existe, não pertence à organização autenticada, ou o id não é um UUID válido.Confirme o id do recurso e que ele pertence à organização da credencial em uso.
PHONE_NUMBER_NOT_FOUNDO fluxo de conexão pública não encontrou o número de telefone associado ao link.Gere um novo link de conexão pública; o número pode ter sido desvinculado da conta da Meta.
CUSTOMER_NOT_FOUNDA organização pediu o portal de cobrança sem nunca ter iniciado uma cobrança.Contrate um plano por POST /api/v1/subscription/checkout antes de abrir o portal.

409

CódigoQuando aconteceComo resolver
SEND_RESULT_UNKNOWNA Meta não confirmou se a mensagem foi aceita e o resultado ficou indeterminado.Não reenvie às cegas: consulte os logs do canal para saber se a mensagem saiu antes de tentar de novo.
CHANNEL_CREDENTIAL_MISSINGO canal não tem uma credencial da Meta armazenada no momento de enviar a mensagem.Reconecte o canal no painel para renovar a credencial antes de tentar enviar novamente.
CHANNEL_NOT_CONNECTEDA operação exige um canal conectado à Meta (com WABA associado) e o canal ainda não está.Conclua a conexão do canal no painel antes de enviar mensagens ou consultar templates por ele.
NOT_PENDING_REGISTRATIONRegistro com PIN pedido para um canal que não está no status connected com número vinculado.Consulte o canal: active já envia; os demais status precisam da conexão pelo link antes do registro.
EXTERNAL_ID_CONFLICTO identificador externo enviado ao criar um canal já está em uso por outro canal ATIVO da organização. Canal excluído não conta: o identificador volta a ficar livre assim que o canal é excluído, então reconectar com o mesmo external_id funciona.Use um identificador externo diferente, ou reutilize o canal existente em vez de criar um novo. Se você acabou de excluir o canal que usava esse identificador, tente de novo: a exclusão libera o valor.
IDEMPOTENCY_KEY_REUSEDA mesma Idempotency-Key foi enviada de novo, mas com um corpo de requisição diferente do original.Gere uma Idempotency-Key nova para cada corpo de requisição distinto; nunca reaproveite o valor com dados diferentes.
OPERATION_IN_PROGRESSJá existe uma operação em andamento para a mesma Idempotency-Key, ainda não concluída.Aguarde e repita a requisição depois — a resposta original é devolvida assim que a operação em curso terminar.
PHONE_ALREADY_CONNECTEDO número de telefone que o cliente final está tentando conectar já está vinculado a outro canal.Desconecte o número do canal anterior antes de conectá-lo a um novo, ou use o canal já existente.
SUBSCRIPTION_ALREADY_EXISTSA organização tentou contratar um plano enquanto já tem uma assinatura em aberto.Cancele ou aguarde a resolução da assinatura existente antes de contratar uma nova.
WABA_AMBIGUOUSA autorização incluiu mais de uma conta do WhatsApp Business e não há como saber qual conectar.Refaça a conexão compartilhando apenas a conta que será conectada a este canal.
CHANNEL_SUSPENDEDA conexão com credenciais foi pedida para um canal suspenso.Regularize a assinatura ou fale com o suporte para reativar o canal antes de conectá-lo.

410

CódigoQuando aconteceComo resolver
MEDIA_EXPIREDA mídia existiu neste canal, mas a Meta já apagou o arquivo — ela guarda o binário por 30 dias após o envio.Não repita a requisição: o arquivo não volta. Baixe e guarde a mídia do seu lado assim que o evento chegar pelo webhook.

413

CódigoQuando aconteceComo resolver
MEDIA_TOO_LARGEO arquivo enviado passa do limite aceito pela Meta para aquele tipo de mídia.Comprima ou reduza o arquivo antes de reenviar.
PAYLOAD_TOO_LARGEO corpo da requisição passa do limite aceito pela API.Divida o envio em requisições menores.
MESSAGE_TOO_LARGEO corpo da mensagem serializado excede 256 KiB, um limite do próprio CRPRO Hub, imposto antes de repassar a mensagem para a Meta.Reduza o conteúdo da mensagem para caber no limite de 256 KiB por payload — veja a tabela de Limites.
WEBHOOK_PAYLOAD_TOO_LARGEO payload serializado de um evento de webhook excede o tamanho máximo aceito para entrega.Isto normalmente não é causado pelo integrador — se aparecer, cite o x-request-id ao abrir suporte.

415

CódigoQuando aconteceComo resolver
UNSUPPORTED_MEDIA_TYPEO content-type enviado não é aceito neste endpoint.Use um dos tipos suportados pela Meta para o formato em questão.

422

CódigoQuando aconteceComo resolver
INVALID_PIN_FORMATO corpo do registro não trouxe o campo pin como string de exatamente 6 dígitos.Envie {"pin":"123456"} — string, só dígitos, seis caracteres. Nada foi enviado à Meta.
REGISTRATION_REJECTEDA Meta recusou o registro do número por um motivo que não é PIN, bloqueio, credencial ou instabilidade.Veja details.meta_code. Com details.reason = on_premises, o número está na API Local e precisa ser desregistrado antes.
WABA_MISSINGA autorização concluída na Meta não incluiu nenhuma conta do WhatsApp Business.Refaça a conexão e, na janela da Meta, selecione (ou cadastre) a conta do WhatsApp Business que será conectada.
PHONE_NUMBER_MISSINGA conta da Meta resolvida pelo link de conexão pública não tem número de telefone associado.Verifique no gerenciador de negócios da Meta se a conta tem um número de telefone configurado, antes de gerar um novo link.
META_APP_SECRET_INVALIDA Meta recusou o App Secret informado para o App ID na conexão com credenciais.Copie de novo o App Secret em Configurações do app > Básico, no painel de desenvolvedores da Meta, e confira se o App ID é do mesmo app.
META_TOKEN_INVALIDO Access Token informado na conexão com credenciais está inválido, expirado ou não é reconhecido para o app.Gere um token novo para o usuário do sistema no Gerenciador de Negócios, com o app informado, e envie as credenciais de novo.
META_TOKEN_APP_MISMATCHO Access Token foi gerado por um app diferente do App ID informado.Gere o token escolhendo o mesmo app do App ID, ou informe o App ID e o App Secret do app que gerou o token.
META_TOKEN_SCOPE_MISSINGO Access Token não tem whatsapp_business_management e whatsapp_business_messaging sobre a WABA informada.Gere o token do usuário do sistema marcando as duas permissões e atribua a WABA a esse usuário antes de gerar.
PHONE_NUMBER_NOT_IN_WABAO Phone Number ID não aparece entre os números da WABA informada, ou o token não enxerga a WABA.Confira os dois IDs em WhatsApp > Configuração da API, no painel do app na Meta, e se a WABA está atribuída ao usuário do sistema.

429

CódigoQuando aconteceComo resolver
RATE_LIMITEDA requisição excedeu um dos limites de taxa da API — geral, de envio por canal, de teste de webhook ou de conexão pública.Reduza a frequência de chamadas e recue antes de tentar de novo — veja a orientação de recuo em Limites.
PIN_LOCKEDTentativas de registro demais: pelo limite do Hub (details.locked_by = hub) ou por bloqueio da Meta (details.locked_by = meta).Aguarde. Com locked_by = hub, respeite retry_after_seconds e o header Retry-After. Com locked_by = meta, a Meta informa o prazo no detalhe do próprio erro, mas o Hub ainda não o repassa (retry_after_seconds vem null); no #133016 a espera é de 72 horas. Cada tentativa nova consome o limite de registro do número.

500

CódigoQuando aconteceComo resolver
INTERNAL_ERROROcorreu um erro não previsto no processamento da requisição.Tente novamente; se persistir, abra um chamado de suporte citando o header x-request-id da resposta.

502

CódigoQuando aconteceComo resolver
META_OAUTH_FAILEDA Meta recusou trocar o código de autorização por um token de acesso.Gere um novo link e refaça a conexão: o código tem validade curta e é de uso único. Se persistir, confira se o endereço de retorno do app na Meta é exatamente https://crprohub.com/connect/retorno.
META_UNREACHABLEA fachada /meta não conseguiu falar com a Meta (falha de rede). A Meta pode ou não ter recebido o pedido.Não repita um envio de mensagem às cegas: confira pelo status do webhook se ela saiu antes de tentar de novo.
META_MEDIA_DOWNLOAD_FAILEDA Meta não entregou o arquivo de uma mídia recebida ao baixar por /meta/_media/{media_id}.Tente o download de novo em alguns minutos; a mídia fica disponível na Meta por 30 dias.
META_RESPONSE_TOO_LARGEA resposta da Meta veio acima do limite que o Hub aceita processar.Reduza o intervalo ou a quantidade de itens pedidos e tente de novo.
STRIPE_CUSTOMER_FAILEDO provedor de cobrança (Stripe) recusou a criação do cliente ao contratar um plano.Tente novamente; se persistir, contate o suporte citando o header x-request-id da resposta.
STRIPE_CHECKOUT_FAILEDO provedor de cobrança (Stripe) recusou a abertura da sessão de checkout.Tente novamente; se persistir, contate o suporte citando o header x-request-id da resposta.
STRIPE_PORTAL_FAILEDO provedor de cobrança (Stripe) recusou a abertura do portal de cobrança.Tente novamente; se persistir, contate o suporte citando o header x-request-id da resposta.
STRIPE_ADDON_FAILEDO provedor de cobrança (Stripe) recusou a alteração da quantidade de conexões adicionais.Confira no portal de cobrança se o cartão da assinatura continua válido e tente novamente.
STRIPE_PREVIEW_FAILEDO provedor de cobrança (Stripe) não conseguiu calcular o valor proporcional da alteração.Tente novamente; se persistir, contate o suporte citando o header x-request-id da resposta.
META_AUTH_FAILEDA credencial da Meta guardada para o canal está inválida, expirada, sem permissão ou indisponível.Refaça a conexão do canal pelo link para o Hub receber uma credencial nova.
META_UNREACHABLEA Meta respondeu com instabilidade ou não pôde ser alcançada durante o registro, a conexão com credenciais ou o upload da amostra de header de template (POST /meta/{waba_id}/header_handle).Tente de novo em instantes.
META_SUBSCRIPTION_FAILEDA Meta recusou assinar o app nos webhooks da WABA durante a conexão com credenciais.Confira se o token tem whatsapp_business_management sobre a WABA e tente de novo. Sem essa assinatura nenhuma mensagem chega.
META_INVALID_RESPONSEA Meta aceitou a chamada de envio, mas devolveu uma resposta sem o identificador da mensagem enviada.Trate como falha de entrega e tente reenviar; se persistir, confirme o status do número no gerenciador de negócios da Meta.
META_SEND_FAILEDA Meta recusou o envio na própria chamada. Muitas recusas não chegam aqui, e sim depois do 202, como message.status com status failed e o código em errors — é o caso do 131049 e do 130472, e costuma ser o do 131026 e do 131047.Consulte o campo meta_code nos detalhes do erro e o significado do código em /docs/erros/meta antes de reenviar.

503

CódigoQuando aconteceComo resolver
HUB_TEMPORARILY_UNAVAILABLEO Hub ficou momentaneamente sem capacidade (banco de dados) para atender a requisição.Tente de novo após o header retry-after. Com x-hub-retry-safe: true, o pedido não chegou à Meta e repetir um envio não duplica a mensagem.
SEND_ACCEPTED_PENDING_PERSISTENCEA mensagem foi aceita pela Meta, mas o registro local ainda não foi gravado.Não reenvie: o registro é reconciliado automaticamente. Consulte os logs do canal para confirmar.

504

CódigoQuando aconteceComo resolver
META_TIMEOUTA Meta não respondeu a tempo à fachada /meta. A Meta pode ter processado o pedido mesmo assim.Não repita um envio de mensagem às cegas: confira pelo status do webhook se ela saiu antes de tentar de novo.
META_UNREACHABLEA Meta não respondeu a tempo durante o registro ou o upload da amostra de header de template (POST /meta/{waba_id}/header_handle).Tente de novo em instantes; no registro, consulte o canal antes — ele pode ter sido concluído.
Estes são os códigos do CRPRO Hub. Os números da Meta — como o 131049 no details.meta_code de um META_SEND_FAILED, ou no errors de um message.status com falha — estão explicados em códigos de erro da Meta.

Códigos de contexto de requisição

Os códigos abaixo não nascem de um endpoint específico — eles vêm da camada de autenticação e contexto de requisição, comum a toda a API, e por isso ficam numa tabela separada.

400

CódigoQuando aconteceComo resolver
INVALID_FROMO parâmetro from do filtro de logs veio com uma data que não pôde ser interpretada.Envie from como uma data ISO 8601 válida, ou omita o parâmetro.
INVALID_TOO parâmetro to do filtro de logs veio com uma data que não pôde ser interpretada.Envie to como uma data ISO 8601 válida, ou omita o parâmetro.
ORGANIZATION_ID_OBRIGATORIOO usuário autenticado por sessão pertence a mais de uma organização e a requisição não enviou o header x-organization-id.Envie o header x-organization-id com o id da organização em que a operação deve acontecer.

401

CódigoQuando aconteceComo resolver
NAO_AUTENTICADONenhuma sessão de painel nem chave de API válida foi encontrada na requisição.Envie o header Authorization: Bearer hub_pk_... ou autentique-se no painel antes de chamar a API.
CREDENCIAL_INVALIDAO valor enviado no header Authorization não corresponde a nenhuma chave de API ativa.Confira se a chave foi copiada por inteiro e se não foi revogada; gere uma nova em /painel/chaves se necessário.
CREDENCIAL_REVOGADAA chave de API usada já foi revogada.Crie uma nova chave em /painel/chaves; uma chave revogada não volta a funcionar.
CREDENCIAL_EXPIRADAA chave de API usada passou da data de expiração configurada na criação.Crie uma nova chave em /painel/chaves, com uma expiração mais longa ou sem expiração.

403

CódigoQuando aconteceComo resolver
SCOPE_INSUFICIENTEA credencial (chave de API, token de canal ou sessão) autenticou com sucesso, mas não tem o escopo exigido pelo endpoint.Use uma credencial com o escopo necessário — veja a tabela de escopo por papel em Autenticação.
SCOPE_DELEGATION_FORBIDDENA criação de uma chave de API pediu um escopo que a credencial atual não possui.Peça apenas escopos que a sessão que está criando a chave já tem — não é possível delegar um escopo que não se possui.
MEMBERSHIP_AUSENTEO usuário autenticado por sessão não pertence a nenhuma organização.Aceite um convite ou crie uma organização no painel antes de chamar a API.

404

CódigoQuando aconteceComo resolver
RECURSO_NAO_ENCONTRADOO header x-organization-id aponta para uma organização à qual o usuário não pertence, ou o recurso pedido é de outra organização.Confira o id da organização e que o usuário é membro dela; o 404 é deliberado em vez de 403, para não confirmar a existência do recurso a quem não tem acesso.

429

CódigoQuando aconteceComo resolver
RATE_LIMITEDA requisição excedeu o limite geral de 120 requisições por minuto por organização e credencial.Reduza a frequência de chamadas e recue antes de tentar de novo — veja a orientação de recuo em Limites.
INVALID_FROM e INVALID_TO, nesta última tabela, vêm do filtro de período em /api/v1/logs. Os demais códigos dessa tabela vêm de qualquer endpoint autenticado, antes mesmo da lógica específica do endpoint rodar.