Códigos de erro da API — como debugar tudo

Toda integração quebra em algum momento — e quando quebra, você precisa entender por que antes de abrir chamado. Esse guia mapeia todos os códigos HTTP que a API PixGo retorna, as mensagens de erro mais comuns, técnicas de debug e como reproduzir bugs com clareza.

Formato padrão das respostas de erro

Toda resposta da API segue um padrão JSON com campos consistentes. Erros têm essa forma:

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Valor deve estar entre R$10 e R$6000",
    "field": "amount",
    "request_id": "req_019c8b91..."
  }
}

Os campos:

• code — identificador técnico do erro (use pra tratamento programático)
• message — descrição em português pra mostrar pro dev (não pro usuário final)
• field — nome do campo problemático (em erros de validação)
• request_id — ID único da requisição. Sempre logue isso — é o que o suporte pede pra investigar.

Tabela completa de códigos HTTP

Erros 4xx mais comuns (e como corrigir)

401 — INVALID_API_KEY

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key não encontrada ou revogada"
  }
}

Causas frequentes:

• Você gerou uma chave nova (a antiga foi invalidada automaticamente)
• Esqueceu de mandar o header X-API-Key
• Colocou espaço/quebra de linha extra na chave (cuidado com copy-paste)
• Conta foi suspensa

Como debugar: copie a chave do Minha Loja novamente e teste com curl:

curl -X POST https://pixgo.org/api/v1/payment/create \
  -H "X-API-Key: pk_chave_atual" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10}'

422 — INVALID_AMOUNT / INVALID_FIELD

Valor fora dos limites do seu nível, mínimo abaixo de R$10, ou campo de tipo errado.

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Valor R$5000 acima do limite atual (R$1500 - nivel Ouro)",
    "field": "amount"
  }
}

Veja seu nível atual em pixgo.org/depix (botão de nível abre modal). Detalhes em Limites por nível.

429 — RATE_LIMIT_EXCEEDED

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de 1000 req/24h excedido no endpoint /status",
    "retry_after_seconds": 60
  }
}

Acontece principalmente no endpoint /payment/{id}/status (cap 1.000/24h). Respeite o Retry-After e considere migrar pra webhook.

410 — PAYMENT_GONE

O depósito existiu mas o registro foi removido (geralmente depósitos expirados há muito tempo viram 410 Gone em vez de 404 Not Found). Não retente.

400 — MALFORMED_JSON

JSON mal formado, falta vírgula, aspas erradas. Valide em jsonlint.com antes de mandar:

{
  "success": false,
  "error": {
    "code": "MALFORMED_JSON",
    "message": "Erro ao parsear JSON na linha 3: aspas não fechada"
  }
}

Erros 5xx — quando NÃO é culpa sua

Códigos 500/502/503/504 indicam problema do lado da PixGo. Boas práticas:

• Implemente retry com backoff exponencial: tentativa 1 → espera 1s → tentativa 2 → espera 2s → tentativa 3 → 4s → tentativa 4 → 8s → desiste e marca pra processamento manual
• Use idempotency: se você está criando pagamento, gere um identificador único (UUID v4) e mande no header Idempotency-Key — em retry, você não cria duplicado
• Não retente em loop infinito: 3-5 tentativas é o teto. Depois, registra pra fila de retry manual
• Logue tudo: timestamp, payload enviado, status retornado, body, headers — em especial o request_id
• Se persistir > 15min: abra chamado em pixgo.org/chamados com o request_id + timestamp + payload sanitizado (sem dados sensíveis)

Exemplo de retry com backoff (PHP)

function callPixgoApi(string $method, string $path, array $body, int $maxRetries = 4): array {
    $attempt = 0;
    $lastError = null;
    while ($attempt < $maxRetries) {
        $resp = httpRequest($method, "https://pixgo.org/api/v1$path", $body);
        if ($resp['status'] >= 200 && $resp['status'] < 300) {
            return $resp;
        }
        // 4xx é culpa nossa, não retentar
        if ($resp['status'] >= 400 && $resp['status'] < 500) {
            throw new RuntimeException("Erro {$resp['status']}: " . ($resp['body']['error']['message'] ?? ''));
        }
        // 5xx: espera e tenta de novo
        $lastError = $resp;
        $waitSec = pow(2, $attempt);  // 1, 2, 4, 8
        sleep($waitSec);
        $attempt++;
    }
    throw new RuntimeException("Falhou após $maxRetries tentativas. Último erro: HTTP {$lastError['status']}");
}

Erros de webhook (do seu lado)

Quando seu endpoint webhook quebra, a PixGo registra e retenta. Erros do seu lado mais comuns:

401 ou 403 retornado pelo seu servidor

Assinatura HMAC inválida — veja o artigo API PixGo v1 — guia para desenvolvedores. Causas:

• Você está usando uma chave diferente da que o webhook foi configurado
• Parsing do body alterou o corpo bruto (use raw body, não JSON.parse antes)
• Encoding errado (UTF-8 vs latin1)
• Trim ou whitespace acidental no timestamp

Timeout (PixGo aguarda 10s, seu endpoint demora mais)

Solução: receba webhook, valide assinatura, enfileire o processamento pesado (queue/job) e responda 200 em < 1s. Detalhes no guia API — boas práticas.

Múltiplos webhooks duplicados sendo processados

Webhook pode chegar mais de uma vez (em caso de retry). Use idempotency no seu lado: (payment_id, event) como chave única.

Como reproduzir um bug pra abrir chamado direito

Quando precisar pedir ajuda, quanto mais info, mais rápido o suporte resolve. Roteiro:

1. Reproduza com curl: tire a sua stack do meio (PHP/Node/Python), use só curl direto. Se o bug acontece no curl, é com a API. Se não acontece, é com o seu código.
2. Capture os 3 elementos:
   • Comando curl EXATO usado (com chave mascarada: pk_***)
   • Resposta completa: status, headers, body
   • Timestamp UTC da request
3. Tente em outra rede: às vezes é firewall corporativo ou proxy bagunçado. Teste do celular em 4G.
4. Confira que não é cache: alguns proxies e CDNs cacheiam GET. Adicione ?nocache=<timestamp> só pra testar.
5. Confira a documentação live: pixgo.org/api/v1/docs tem o estado atual da API. Algumas mudanças recentes podem não estar em blog posts antigos.

Template de chamado pra problema de API

Assunto: [API] [POST /payment/create] HTTP 500 intermitente

ID da minha PixGo Key: pk_*** (últimos 4: ABCD)
Hora UTC da falha: 2026-05-15T14:23:45Z
Request ID retornado: req_019c8b91...
Endpoint: POST /api/v1/payment/create

Comando curl mínimo que reproduz:

curl -X POST https://pixgo.org/api/v1/payment/create \
  -H "X-API-Key: pk_***" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "description": "teste"}'

Resposta esperada: 201 Created com objeto payment
Resposta recebida: HTTP 500
  body: {"success": false, "error": {"code": "INTERNAL_ERROR", ...}}

Comportamento: acontece em ~10% das tentativas, sem padrão claro
Frequência: 5 falhas nas últimas 50 requests
Já tentei: retry (não resolveu), gerar nova chave (não resolveu)

Com esse template, o suporte tem TUDO que precisa pra investigar — costuma resolver em uma rodada de resposta.

Ferramentas que ajudam no debug

• Postman / Insomnia: GUI pra testar API sem precisar lembrar sintaxe do curl. Salva collections com chave + endpoints. Ótimo pra explorar.
• ngrok / Cloudflare Tunnel: testa webhook no seu localhost. Cria um túnel HTTPS público apontando pro seu localhost:3000.
• jq: parser de JSON em linha de comando. Mata o "vou copiar e colar o JSON num site formatado".
• httpbin.org: serviço público que devolve o que você manda. Útil pra ver exatamente o que seu cliente HTTP está enviando (caso suspeite que o body está sendo modificado).
• Browser DevTools → Network: se sua integração roda no front (não deveria pra API key, mas pra páginas do pay/), olhe o tráfego HTTP direto no Chrome/Firefox.

Quando o problema é seu (e você está culpando a API)

Lista honesta dos casos em que você ACHA que é bug da PixGo mas é seu:

• Cliente JavaScript com CORS: você não pode chamar a API direto do navegador — chave de produção não pode ir pro front. Use seu backend como intermediário.
• Body sendo modificado por middleware: frameworks como Express + body-parser podem modificar o JSON antes da assinatura HMAC. Use raw body pra validação.
• Timezone errado no timestamp: PixGo envia em UTC. Se você converte pra local timezone antes de comparar com a assinatura, vai bater errado.
• Encoding: arquivo PHP salvo em latin1, JSON contém caracteres especiais → assinatura HMAC não bate.
• Retry sem idempotency: você gera 2 pagamentos quando o primeiro deu timeout (era 200 OK, só não chegou de volta). Use UUID por pedido.
• Polling do endpoint /status a cada 100ms: vai estourar o rate limit em segundos. Use webhook.

Status público da API

Hoje a PixGo não tem uma status page dedicada (tipo status.pixgo.org). Pra confirmar se uma instabilidade é do nosso lado:

• Tente acessar pixgo.org/api/v1/docs — se carrega, o backend está vivo
• Tente um POST /payment/create com R$10 do curl — se retorna 201, tudo OK
• Verifique nosso Telegram @PixGoOrg — anunciamos manutenção e incidentes lá
• Se nada disso funciona, abre chamado mesmo sem ter certeza — pode ser real

Resumo prático

• 4xx = seu problema (geralmente fix rápido lendo a message)
• 5xx = problema PixGo (retry com backoff, logar request_id)
• 429 = você atropelou rate limit (use webhook em vez de polling)
• Webhook quebrando: verifique HMAC, encoding, timeout, idempotency
• Antes de chamado: reproduza com curl, capture request+response+timestamp+request_id
• Idempotency keys + retry com backoff exponencial = integração robusta

Leituras relacionadas: API PixGo v1 — guia completo · Recorrência via API · ChatGPT como copiloto pra integração