Erros

Todo erro da API vem como JSON com um campo:

{ "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

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

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

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

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.

Comece por aqui

Receber

Produtos e entrega

Dinheiro na conta

Referência rápida

Códigos

Mensagens que você vai encontrar

Como tratar