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

# Erros

> Um formato só, sete códigos, e quais deles vale reenviar.

Todo erro da API vem como JSON com um campo:

```json theme={null}
{ "error": "Descrição do que deu errado" }
```

> [!WARNING]
>
> Trate erro pelo **código HTTP**, nunca pelo texto. A mensagem existe para você ler no
> log e pode mudar sem aviso. O código não muda.

## Códigos

| Código | Significa | Reenviar? |
| - | - | - |
| `400` | Parâmetro ausente, inválido ou fora do limite | Só depois de corrigir |
| `401` | Chave ausente, inválida, revogada ou com prefixo errado | Não. Veja [Autenticação](https://docs.purin.cash/guias/autenticacao.md) |
| `403` | Chave válida, operação não permitida (sandbox com chave live, conta sem verificação) | Não. Resolva no painel |
| `404` | Recurso não existe ou não é da sua conta | Não |
| `409` | Conflito de estado (saque turbo já em andamento) | Sim, depois de esperar |
| `429` | Passou do [limite de requisições](https://docs.purin.cash/guias/limites.md) | Sim, com backoff |
| `500` | Erro inesperado no servidor | Sim, com backoff |
| `502` | Falha temporária junto ao provedor | Sim, com backoff |
| `503` | Recurso indisponível no momento (carteira LTC ausente, cripto fora do ar) | Sim, mais tarde |

> [!NOTE]
>
> `404` em vez de `403` para recurso de outra conta é proposital. A API não confirma que um
> id existe se ele não é seu.

## Mensagens que você vai encontrar

> [accordion] Validação (400)
>
> | Mensagem | Causa |
> | - | - |
> | `valueCents must be >= 80 (R$ 0.80), or provide productId` | Valor abaixo do mínimo da loja. O número na mensagem é o mínimo real da sua conta |
> | `priceCents must be >= 100 (R$ 1.00)` | Produto abaixo de R\$ 1,00 |
> | `callbackUrl must be a valid, public HTTPS URL` | URL sem HTTPS, com IP, `localhost` ou rede privada |
> | `paymentMethod must be 'pix' or 'ltc'` | Método desconhecido |
> | `Invalid product ID format` | O id não é um ObjectId válido |

> [accordion] Autenticação (401)
>
> | Mensagem | Causa |
> | - | - |
> | `API key required. Use: Authorization: Bearer ps_live_...` | Header ausente ou malformado |
> | `Invalid API key prefix. Use ps_live_ or ps_test_` | Prefixo desconhecido |
> | `Invalid or revoked API key` | Chave inexistente ou revogada |
> | `API key environment mismatch. Please generate a new key.` | Prefixo não bate com o ambiente da chave |

> [accordion] Permissão (403)
>
> | Mensagem | Causa |
> | - | - |
> | `Sandbox endpoint requires ps_test_ key` | Rota de sandbox chamada com chave de produção |
> | `PIX not verified. Complete verification in the dashboard first.` | Saque antes de verificar a chave PIX |

> [accordion] 404 e 502
>
> | Mensagem | Causa |
> | - | - |
> | `Product not found` | Produto inexistente, inativo ou de outra conta |
> | `Charge not found` | Cobrança inexistente ou de outra conta |
> | `Payment not found` | Pagamento inexistente ou de outra conta |
> | `LTC price unavailable` | Cotação de Litecoin fora do ar no momento |

## Como tratar

```js theme={null}
async function chamar(url, opcoes, tentativas = 4) {
  for (let i = 0; i < tentativas; i++) {
    const res = await fetch(url, opcoes);
    if (res.ok) return res.json();

    const { error } = await res.json().catch(() => ({ error: res.statusText }));

    // Erro do cliente: reenviar não resolve, só queima requisição.
    if (res.status < 500 && res.status !== 429) {
      throw new Error(`${res.status}: ${error}`);
    }

    // 429, 5xx: vale esperar. Backoff com jitter pra não sincronizar rajada.
    const espera = 2 ** i * 1000 + Math.random() * 1000;
    await new Promise((r) => setTimeout(r, espera));
  }
  throw new Error("limite de tentativas excedido");
}
```

> [!TIP]
>
> Registre o corpo `{ "error": ... }` junto do código HTTP e do `paymentId` nos seus logs.
> Quando você chamar a gente [no Discord](https://discord.gg/8eyQQFZZxY), é essa tripla que
> resolve em uma resposta em vez de cinco.


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