Troubleshooting

Guia prático para os erros e situações que mais aparecem em integração. Cada seção tem o sintoma, a causa provável e o que checar.

Recebi `no_routing_rule` ao criar pagamento

Sintoma: POST /v1/payments responde 409 no_routing_rule.

Causa: o ambiente da API key usada não tem nenhuma regra de roteamento ativa para o método (pix ou card) da requisição.

O que checar:

No painel, vá em Projeto → Roteamento e confirme que existe uma regra para o método no ambiente correspondente (sandbox/production).
Confirme que a API key usada no header Authorization pertence ao mesmo ambiente: uma chave sk_test_… só vê regras de sandbox; sk_live_… só vê produção.
Se a regra existe mas o erro persiste, o gateway apontado pode estar desativado: nesse caso a API retorna provider_disabled, não no_routing_rule. Veja a lista em Erros.

Recebi `provider_not_configured` ou `provider_disabled`

Sintoma: 409 com mensagem indicando o gateway.

Causa:

provider_not_configured: existe uma regra de roteamento apontando para um gateway que não tem credenciais cadastradas naquele ambiente.
provider_disabled: o gateway tem credenciais, mas o toggle está desligado em Projeto → Gateways.

O que fazer: ou cadastre as credenciais, ou ative o gateway, ou troque a regra de roteamento para apontar para outro provider já ativo.

Recebi `signature_invalid` no webhook

Sintoma: o endpoint do cliente que recebe webhooks da Allya retornou erro indicando que a assinatura está inválida.

Checklist:

Use o body cru (req.text(), não req.json()) para computar o HMAC. Re-serializar via JSON.parse + JSON.stringify produz uma string diferente da assinada.
Compare como {timestamp}.{body}: concatene X-Allya-Timestamp + . + body bruto antes do HMAC-SHA256. Erro comum é assinar só o body.
Use o secret do endpoint, não o do gateway. O secret retornado quando você cria/rotaciona o endpoint no painel é único e diferente do Webhook Secret do gateway.
Confirme que o secret não foi rotacionado sem atualizar o .env da sua aplicação.
Compare em tempo constante (timingSafeEqual): comparações com === em strings vazam timing.
Rejeite timestamps muito velhos (mais de 5 minutos) para evitar replay. Veja o exemplo completo em Webhooks.

Pagamento ficou em `processing` por muito tempo

Sintoma: GET /v1/payments/:id continua devolvendo status: "processing" muito depois do esperado.

Causa provável: o webhook do gateway não chegou ou chegou e foi rejeitado, e o status na Allya não foi reconciliado.

O que fazer:

Force um sync com o gateway: POST /v1/payments/:id/sync. Isso consulta o gateway na hora e atualiza o status local. Veja Sincronizar pagamento.
Se mesmo após o sync o status continua processing, verifique no painel da Allya (Pagamento → Logs) se há entradas WEBHOOK_RECEIVED para esse pagamento. Falta delas indica que o webhook do gateway nunca chegou.
No painel do gateway (Abacate Pay / Asaas / Pagar.me), confirme se a URL de webhook está apontando para a Allya e ativa.
No fluxo Pagar.me com cartão, status authorized em auth_and_capture agora aparece como processing para sinalizar captura pendente. Espere o payment.paid natural ou rode sync para confirmar.

Recebi `rate_limit_exceeded`

Sintoma: 429 em POST /v1/payments com header Retry-After.

Causa: a API key excedeu o limite de requisições por minuto (default 30/min).

O que fazer:

Implemente retry honrando Retry-After. Veja o exemplo em Criar pagamento.
Se o burst é legítimo (lote de cobranças), espalhe as requisições no tempo ou contate o administrador do projeto para avaliar aumento do limite operacional.
Se você não esperava esse volume, pode ser sinal de chave comprometida: revogue e gere outra em Projeto → API keys.

Webhook outbound marcou `FAILED` no painel

Sintoma: lista de "Webhooks enviados" no detalhe do pagamento mostra FAILED com HTTP 5xx ou erro de rede.

O que fazer:

Confira se seu endpoint estava acessível no momento do envio (logs/uptime).
Use o botão Reenviar ao lado da entrega: recria o envio usando o payload original e a mesma assinatura.
Se o endpoint mudou de URL, atualize em Projeto → Webhooks. Reenvios continuam apontando para a URL atualmente cadastrada no endpoint.

Idempotência: criei dois pagamentos com o mesmo `externalId` por engano

A Allya garante idempotência por (environmentId, externalId). A segunda criação com o mesmo externalId não dispara cobrança nova: retorna o pagamento existente. Confirme em Idempotência.

Se você precisa criar uma nova cobrança para o mesmo pedido (ex.: cliente abandonou e retornou depois), use um externalId distinto (ex.: sufixo -r2).

Webhook chega na Allya mas outbound não dispara

Sintoma: o painel mostra WEBHOOK_RECEIVED para o pagamento, mas Webhooks → Histórico de entregas está vazio.

Causa provável: o evento atualizou o pagamento para processing (status intermediário): esse status não gera webhook outbound.

O que fazer:

Verifique o status atual em Pagamento → detalhe. Se for processing, é esperado.
Espere o próximo evento do gateway (ex.: paid) ou force POST /v1/payments/:id/sync para reconciliar.
Se o evento que chegou era paid mas mesmo assim não saiu outbound, confira:
- O endpoint cadastrado está com enabled=true?
- O enabledEvents do endpoint inclui payment.paid (ou está vazio = todos)?
- O endpoint passou em validação de URL HTTPS pública (URLs internas/privadas são bloqueadas)?

Veja WEBHOOK_FAILED em Logs se a Allya tentou e falhou no envio.

Como saber qual gateway atendeu uma chamada

Toda resposta de POST /v1/payments, POST /v1/subscriptions, GET /v1/payments/:id etc. inclui o campo gateway:

{
  "id": "pay_7f3e0c9a12b44d63a9f612c42a8d2b90",
  "status": "pending",
  "method": "pix",
  "gateway": "abacate_pay",
  ...
}

Valores possíveis: "abacate_pay", "asaas", "pagarme". Útil para correlacionar com o painel do provedor durante investigação. O painel da Allya também mostra o gateway no detalhe de cada pagamento.

Pagamento de sandbox aparece em produção (ou vice-versa)

Não. Sandbox e produção são completamente isolados: ambientes diferentes, gateways diferentes, API keys diferentes, banco com environmentId denormalizado em cada registro relevante.

Se você vê algo inesperado, confira:

Qual API key foi usada? sk_test_… lê só sandbox; sk_live_… só produção.
Qual ambiente o switcher do painel está mostrando? Quem cria um pagamento via API com sk_live_ mas olha o painel em sandbox vê "está vazio": está, em sandbox.

Erro `gateway_error` 502: por onde começar

502 gateway_error significa que a chamada ao gateway falhou. A Allya devolve provider no payload do erro:

{ "error": "gateway_error", "provider": "pagarme" }

Passos:

Confira os logs em Pagamento → detalhe → Logs ou Projeto → Logs. A entrada GATEWAY_ERROR traz o código HTTP e a mensagem retornada pelo gateway (sanitizada).
Se o erro for 401/403 do gateway: credenciais do gateway estão erradas ou foram revogadas no painel do provedor. Revise em Gateways → editar.
Se for 4xx com mensagem de validação: o adapter pode estar mandando algo que o gateway recusou. Compare o payload bruto (visível em log) com a documentação do gateway.
Se for 5xx ou timeout: gateway instável. Retentar com backoff (a resposta 502 da Allya é seguro retentar por causa de idempotência).
Cheque a status page do gateway (Abacate Pay, Asaas, Pagar.me): pode ser incidente do lado deles.

Se persistir após troca de credencial e gateway saudável, abra issue com paymentId (sem dados sensíveis) e o trecho do log.

API key acabou de virar `sk_live_` e tudo está 401

Causa: a chave sk_live_ é nova e ainda não foi propagada para todos os serviços, ou o ambiente da chave não bate com o ambiente esperado pela aplicação.

Checklist:

Você gerou a chave em Production (não sandbox)? Confira no painel.
GET /v1/auth/test com a chave retorna environment.kind: "production"?
O secret manager do seu sistema foi atualizado com a nova chave? Em deploys com cache, pode demorar para invalidar.
Você revogou a chave de sandbox por engano? Chaves revogadas mostram badge no painel.

Veja Indo para produção para checklist completo de migração.

Veja também

Erros: hierarquia de códigos e formato do payload.
Logs: primeira ferramenta de investigação.
Autenticação: debug de 401.
Rate limiting: backoff em 429.

On this page