# Problemas comuns

> Índice por sintoma dos problemas mais comuns de integração, com a causa provável e a página que resolve cada um.

Página: https://doc.rapidchargeback.com/referencia/problemas-comuns/

Achou o seu sintoma? A causa provável está em uma linha, e o detalhe na página do link.

## Credenciais e acesso

### Toda chamada responde `401`

O header `Authorization` não bate: credencial errada, regenerada no painel (a anterior deixa de valer na hora) ou base64 montado sobre algo diferente de `client_id:client_secret`. Ver [Autenticação](https://doc.rapidchargeback.com/referencia/autenticacao/).

### A API responde `403 COMPANY_BLOCKED`

A empresa está bloqueada na Rapid. As chamadas por credencial param; os webhooks continuam chegando. Ver [Empresas bloqueadas](https://doc.rapidchargeback.com/canais/webhook/retries-e-logs/#empresas-bloqueadas).

### Recebo `429`

Passou do limite de requisições. Espere o tempo do header `Retry-After` e, para volume, use o envio em lote. Ver [Rate limit](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/#rate-limit).

### Recebo `404 NOT_FOUND` num endpoint que existe

O caminho tem diferença: barra sobrando no fim, `/api/v1` faltando ou erro de digitação. Ver [Códigos de resposta](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/).

## Webhook

### Nenhum webhook chega

Primeiro confira se o webhook está cadastrado e ativo em **Configurações › Webhook**: sem isso não há entrega nem registro no log. Depois, veja o motivo de cada tentativa no log de entregas do painel, em **Atividade**, aba **Webhooks**: ele começa com `[https]`, `[destino]`, `[redirecionamento]` ou `[assinatura]` quando a falha não foi uma resposta do seu servidor. Ver [Retries e logs](https://doc.rapidchargeback.com/canais/webhook/retries-e-logs/#logs-de-entrega).

### A assinatura nunca bate

Quase sempre o corpo foi lido como JSON antes de validar: a assinatura é sobre o corpo bruto, byte a byte. Outras causas: chave já trocada e timestamp fora da janela. Teste com o [conferidor de assinatura](https://doc.rapidchargeback.com/canais/webhook/autenticacao/#conferidor-de-assinatura) e compare com os exemplos em [Autenticação do webhook](https://doc.rapidchargeback.com/canais/webhook/autenticacao/).

### O log mostra falha, mas o meu servidor recebeu

O seu servidor respondeu fora de `2xx` ou demorou mais que o tempo limite. Ver [O que conta como sucesso](https://doc.rapidchargeback.com/canais/webhook/retries-e-logs/#o-que-conta-como-sucesso).

### O mesmo alerta chegou duas vezes

É retentativa ou reenvio, com o mesmo `alert_id`. Ver [Idempotência](https://doc.rapidchargeback.com/canais/webhook/boas-praticas/#idempotência).

## Alertas

### `422 ALERT_INVALID_STATUS` ao responder um alerta

O prazo passou ou o alerta já tem status definitivo. A mensagem diz qual dos casos. Ver [Transição não permitida](https://doc.rapidchargeback.com/callback/atualizar-status/#transição-não-permitida).

### Não sei o `id` do alerta, só o do provedor

Busque pelo `provider_alert_id`. Ver [Buscar pelo seu próprio ID](https://doc.rapidchargeback.com/callback/consultar-alertas/#buscar-pelo-seu-próprio-id-do-provedor).

## Transações

### `409 TRANSACTION_DUPLICATE`

Já existe transação sua com o mesmo `external_source` e `external_id`. Ver [Códigos de erro](https://doc.rapidchargeback.com/canais/transactions/codigos-de-erro/).

### `409 TRANSACTION_IMMUTABLE`

A transação já foi usada por um produto e não pode mais ser alterada nem apagada. Ver [Proteção de imutabilidade](https://doc.rapidchargeback.com/canais/transactions/visao-geral/#proteção-de-imutabilidade).

### `404 MERCHANT_NOT_FOUND`

O `merchant_id` não é de um merchant da sua empresa. Ver [Listar merchants](https://doc.rapidchargeback.com/canais/merchants/listar-merchants/).

### Perdi o `id` da transação

Ache pelo identificador que você enviou. Ver [Pelo ID do seu sistema](https://doc.rapidchargeback.com/canais/transactions/consultar-transacao/#pelo-id-do-seu-sistema).

### `413 PAYLOAD_TOO_LARGE` no envio em lote

O corpo passou do tamanho máximo. Divida em lotes menores. Ver [Envio em lote](https://doc.rapidchargeback.com/canais/transactions/envio-em-lote/).

### A resposta traz `warnings`

A transação foi criada, mas faltam campos que melhoram a proteção. Ver [Warnings](https://doc.rapidchargeback.com/canais/transactions/criar-transacao/#warnings).

### Disputa chegou sem a transação associada

A transação não tem o identificador da cobrança no gateway. Ver [Nota sobre `transaction_id`](https://doc.rapidchargeback.com/canais/transactions/criar-transacao/#nota-sobre-transaction_id).