> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyxpag.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de problemas

> Diagnostique erros de autenticação, cobrança, transferência, webhook, assinatura, limite de requisições e saldo na NyxPag API, passo a passo.

Procure o sintoma, siga os passos na ordem. A maioria dos problemas se resolve lendo o **`error.code`** da resposta, então comece sempre por ele.

## Antes de abrir um chamado

<Steps>
  <Step title="Guarde o requestId">
    Toda resposta, de sucesso ou erro, traz `requestId`. É o protocolo da requisição.
  </Step>

  <Step title="Reproduza com cURL">
    Isola o problema do seu código e do seu cliente HTTP.
  </Step>

  <Step title="Envie ao suporte">
    Mande o `requestId`, o cURL **sem a sua chave**, o horário com fuso e o que você esperava, para [suporte@nyxpag.com.br](mailto:suporte@nyxpag.com.br).
  </Step>
</Steps>

## Autenticação

<AccordionGroup>
  <Accordion title="401 invalid_api_key">
    A chave está ausente, mal formada, não existe ou foi revogada.

    <Steps>
      <Step title="Confira o cabeçalho">
        Precisa ser `Authorization: Bearer nyx_live_...`, com a palavra `Bearer` e um espaço.
      </Step>

      <Step title="Confira a chave">
        Sem espaço ou quebra de linha no final, ao copiar. Ela começa com `nyx_`.
      </Step>

      <Step title="Confira no dashboard">
        Em [Chaves de API](https://nyxpag.com.br/dashboard/credentials), veja se ela segue ativa. Uma chave **renovada** invalida a anterior na hora.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="403 permission_denied">
    A chave é válida, mas não tem a permissão do endpoint. A `message` diz qual: `Permissão necessária: payments:write.`

    Crie uma nova chave com a permissão. Veja [Gestão de chaves](/guides/comece-aqui/api-key).
  </Accordion>

  <Accordion title="403 ip_not_allowed">
    A chave está restrita a IPs e a requisição saiu de outro. Chame a partir do IP autorizado, ou peça ao [suporte](mailto:suporte@nyxpag.com.br) para atualizar a lista. Em ambiente serverless, o IP de saída muda: use um NAT com IP fixo.
  </Accordion>

  <Accordion title="403 kyc_required">
    A conta ainda não concluiu a verificação de identidade. Conclua no dashboard.
  </Accordion>

  <Accordion title="403 account_unavailable">
    A conta está bloqueada ou indisponível. Fale com o suporte.
  </Accordion>
</AccordionGroup>

## Cobranças

<AccordionGroup>
  <Accordion title="400 ao criar a cobrança">
    Leia a `message`. Os motivos mais comuns:

    | Mensagem | Correção |
    | - | - |
    | Informe o nome completo do pagador | `payer.name` com pelo menos 3 caracteres |
    | Informe um CPF válido para o pagador | Use um CPF válido (o campo não aceita CNPJ) |
    | O valor informado está fora dos limites configurados para Pix | Valor entre R\$ 1,00 e R\$ 10.000,00 |
    | O valor precisa ser maior que a taxa da operação | Aumente o `amount` |
    | Envie Idempotency-Key (ou externalId) | Falta a chave de idempotência |
  </Accordion>

  <Accordion title="Recebi 201 mas o pedido não foi pago">
    É o esperado: `201` só diz que a cobrança **existe**. O pagamento chega depois, em `transaction.approved`. Libere o pedido apenas com `status: "approved"`.
  </Accordion>

  <Accordion title="O cliente pagou e o meu pedido não liberou">
    O dinheiro entrou, então o problema está no seu receptor de webhook.

    <Steps>
      <Step title="Consulte a transação">
        `GET /transactions/{externalId}`. Se vier `approved`, o pagamento está certo e o seu webhook falhou.
      </Step>

      <Step title="Veja se o webhook chegou">
        Confira os logs do seu servidor na hora do pagamento. Se não chegou, veja [Webhook não chega](#webhook).
      </Step>

      <Step title="Veja se a assinatura foi rejeitada">
        Um receptor que valida errado descarta o evento válido. Veja [Assinatura inválida](#webhook).
      </Step>

      <Step title="Rode a conciliação">
        Um job que lista as transações `approved` recentes resolve pedidos presos. Veja [Acompanhar](/guides/pix/acompanhar).
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="O QR Code não aparece na página">
    `qrCodeBase64` vem **sem** o prefixo `data:image`. Monte o `src` assim:

    ```html theme={"dark"}
    <img src="data:image/png;base64,{qrCodeBase64}" alt="QR Code Pix" />
    ```
  </Accordion>

  <Accordion title="O Copia e Cola não valida no banco">
    Use o texto **exatamente** como veio em `pix.copyPaste`. Espaço, quebra de linha ou truncamento invalida o código.
  </Accordion>

  <Accordion title="Reenviei a cobrança e veio a antiga, já cancelada">
    A chave de idempotência não expira e aponta para a operação original. Para refazer depois de a cobrança terminar, use uma chave nova (`PEDIDO-1042-t2`). Veja [Idempotência](/guides/idempotencia).
  </Accordion>

  <Accordion title="O valor do Pix é maior do que o amount que enviei">
    Você usou `coverFee: true`. O `amount` da **resposta** é o que o pagador paga e inclui a tarifa. Veja [coverFee](/guides/pix/receber).
  </Accordion>
</AccordionGroup>

## Transferências

<AccordionGroup>
  <Accordion title="409 WITHDRAWAL_IN_PROGRESS">
    Já existe uma transferência `pending` na conta. Só pode haver uma por vez. Espere `transaction.approved` ou `failed` da anterior e envie a próxima. Enfileire do seu lado.
  </Accordion>

  <Accordion title="422 Saldo insuficiente">
    O disponível não cobre o valor mais a tarifa. Confira com [`GET /balance`](/guides/pix/saldo). Lembre que `coverFee: true` (o padrão) soma a tarifa ao que sai do saldo.
  </Accordion>

  <Accordion title="423: saques bloqueados">
    A administração bloqueou temporariamente os saques da conta. Fale com o suporte.
  </Accordion>

  <Accordion title="400: informe o valor para pagar este Pix Copia e Cola">
    O código é **estático e sem valor**. Envie `amount`. Quando o código já tem valor, omita `amount`.
  </Accordion>

  <Accordion title="400: chave Pix e tipo de chave são obrigatórios">
    Em `pix_key`, envie `destination.value` e `destination.keyType` (`cpf`, `cnpj`, `email`, `phone` ou `random`), e confira que o tipo bate com o formato da chave.
  </Accordion>

  <Accordion title="Fiz a transferência e continua pending">
    Pode demorar. `202` e `pending` com `processingState: "reconciling"` significam que a NyxPag está conferindo o resultado. Aguarde o webhook. Não envie de novo: reenviar com **outra** chave cria um segundo envio.
  </Accordion>
</AccordionGroup>

## Webhook

<AccordionGroup>
  <Accordion title="O webhook não chega">
    <Steps>
      <Step title="A URL é aceitável?">
        HTTPS, porta 443, sem usuário e senha, sem `#`, e que **não** resolva para rede privada nem `localhost`. Veja [as regras](/guides/webhooks).
      </Step>

      <Step title="A URL redireciona?">
        Redirecionamentos não são seguidos e contam como falha. Cadastre a URL final.
      </Step>

      <Step title="O endpoint responde 2xx em até 8 segundos?">
        Qualquer outra resposta, ou demora, conta como falha e agenda nova tentativa.
      </Step>

      <Step title="Há endpoint vinculado à chave?">
        Em [Dashboard → Webhooks](https://nyxpag.com.br/dashboard/webhooks), confira se há um endpoint para a chave que criou a operação. Ou envie `webhookUrl` na requisição.
      </Step>

      <Step title="Já esgotou as tentativas?">
        Depois de 8 falhas a NyxPag não tenta mais. Recupere pelo `GET /transactions`.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Assinatura inválida">
    Em ordem de probabilidade:

    <Steps>
      <Step title="Corpo reserializado">
        Valide sobre o corpo **bruto**. Fazer `JSON.parse` e `JSON.stringify` muda a ordem e o espaçamento.
      </Step>

      <Step title="Chave errada">
        A chave é o **segredo do webhook** (do dashboard), não a API Key.
      </Step>

      <Step title="Segredo rotacionado">
        Depois de **Rotacionar segredo**, o antigo deixa de assinar. Atualize o seu servidor.
      </Step>

      <Step title="Proxy alterando o corpo">
        Nginx, Cloudflare ou um API Gateway que reescrevem ou comprimem o corpo quebram a assinatura. Teste com o [vetor de teste](/webhooks/assinatura).
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Recebi o mesmo evento várias vezes">
    É esperado: a entrega é ao menos uma vez, e vem de novo quando a sua resposta não foi `2xx`. Deduplique pelo `id` do evento (`transaction.*`) ou pelo `X-NyxPag-Delivery` (`med.*`).
  </Accordion>

  <Accordion title="O webhook chega mas o meu processamento falha">
    Se você faz trabalho pesado antes de responder, estoura o limite de 8 segundos. Grave o evento numa fila, responda `2xx` e processe fora do request.
  </Accordion>
</AccordionGroup>

## Limites

<AccordionGroup>
  <Accordion title="429 rate_limit_exceeded">
    Passou de 100 requisições em 60 segundos na chave.

    <Steps>
      <Step title="Espere o Retry-After">
        Está no cabeçalho, em segundos.
      </Step>

      <Step title="Ache o que consome a cota">
        Quase sempre é polling com `refresh=true`. Troque por webhook.
      </Step>

      <Step title="Separe as cargas">
        Use uma chave para o checkout e outra para relatórios.
      </Step>
    </Steps>

    Veja [Limites](/guides/confiabilidade/limites).
  </Accordion>
</AccordionGroup>

## Saldo

<AccordionGroup>
  <Accordion title="O reservado é diferente do que eu esperava">
    O `reserved` guarda o que ainda não está livre: transferências em andamento e a parte de vendas retida pela política de reserva da conta. Ele é liberado ou debitado quando a operação termina. Veja [Saldo](/guides/pix/saldo).
  </Accordion>

  <Accordion title="Um valor foi retido depois de uma venda aprovada">
    Pode ser uma contestação MED. Consulte `GET /meds`. Veja [Contestações (MED)](/guides/disputas/med).
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Erros" icon="triangle-alert" href="/guides/erros">
    O catálogo completo de códigos de erro.
  </Card>

  <Card title="Antes de ir para produção" icon="list-checks" href="/guides/confiabilidade/checklist-producao">
    Evite os problemas antes que aconteçam.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.