{ "error": "Descrição do que deu errado" }
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 |
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 | 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 |
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
400 — validação
400 — validação
| 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 |
Turbo payouts are PIX-only. | turbo: true com method diferente de pix |
401 — autenticação
401 — autenticação
| 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 |
403 — permissão
403 — permissão
| 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 |
404 e 502
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
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");
}
Registre o corpo
{ "error": ... } junto do código HTTP e do paymentId nos seus logs.
Quando você chamar a gente no Discord, é essa tripla que
resolve em uma resposta em vez de cinco.