API error codes — how to debug everything

Every integration breaks at some point — and when it breaks, you need to understand why before opening a ticket. This guide maps every HTTP code the PixGo API returns, the most common error messages, debug techniques, and how to reproduce bugs clearly.

Standard error response format

Every API response follows a consistent JSON pattern. Errors look like this:

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be between R$10 and R$6000",
    "field": "amount",
    "request_id": "req_019c8b91..."
  }
}

The fields:

• code — technical identifier (use it for programmatic handling)
• message — description in Portuguese to show to the dev (not the end user)
• field — name of the problematic field (in validation errors)
• request_id — unique request ID. Always log it — this is what support asks for.

Full HTTP code table

Most common 4xx errors (and how to fix)

401 — INVALID_API_KEY

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key not found or revoked"
  }
}

Common causes:

• You generated a new key (the old one was auto-invalidated)
• Forgot the X-API-Key header
• Extra space/newline in the key (mind copy-paste)
• Account was suspended

How to debug: copy the key from My Store again and test with curl:

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

422 — INVALID_AMOUNT / INVALID_FIELD

Amount outside your tier limits, minimum below R$10, or wrong field type.

See your current tier at pixgo.org/depix (tier button opens modal). Details in Per-tier limits.

429 — RATE_LIMIT_EXCEEDED

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "1000 req/24h limit exceeded on /status endpoint",
    "retry_after_seconds": 60
  }
}

Happens mainly on /payment/{id}/status (1,000/24h cap). Respect Retry-After and consider migrating to webhook.

5xx errors — when it's NOT your fault

500/502/503/504 codes indicate problem on PixGo's side. Best practices:

• Implement retry with exponential backoff: attempt 1 → wait 1s → attempt 2 → wait 2s → attempt 3 → 4s → attempt 4 → 8s → give up and mark for manual processing
• Use idempotency: if you're creating a payment, generate a unique identifier (UUID v4) and send via header Idempotency-Key — on retry, you won't create duplicates
• Don't retry in infinite loop: 3-5 attempts is the ceiling. After that, queue for manual retry
• Log everything: timestamp, payload sent, status returned, body, headers — especially request_id
• If persists > 15min: open ticket at pixgo.org/chamados with request_id + timestamp + sanitized payload

How to reproduce a bug to open a ticket properly

When you need help, the more info, the faster support fixes. Roadmap:

1. Reproduce with curl: take your stack out (PHP/Node/Python), use raw curl. If the bug happens in curl, it's the API. If not, it's your code.
2. Capture the 3 elements: exact curl command (with key masked), full response (status, headers, body), UTC timestamp.
3. Try another network: sometimes it's corporate firewall or messed-up proxy. Test from mobile 4G.
4. Verify it's not cache: some proxies and CDNs cache GET. Add ?nocache=<timestamp> just to test.
5. Check the live docs: pixgo.org/api/v1/docs has the current API state.

Tools that help debug

• Postman / Insomnia: GUI to test API without remembering curl syntax. Saves collections.
• ngrok / Cloudflare Tunnel: tests webhook on your localhost. Creates a public HTTPS tunnel to localhost:3000.
• jq: command-line JSON parser. Kills "let me copy this JSON to a formatter site".
• httpbin.org: public service that echoes what you send. Useful to verify exactly what your HTTP client is sending.

When the problem is yours (and you're blaming the API)

• JavaScript client with CORS: you can't call the API from the browser — production key can't go to front. Use your backend as intermediary.
• Body modified by middleware: frameworks like Express + body-parser may alter JSON before HMAC signature. Use raw body for validation.
• Wrong timezone in timestamp: PixGo sends in UTC. If you convert to local before comparing signature, it won't match.
• Encoding: PHP file saved in latin1, JSON with special chars → HMAC signature mismatch.
• Retry without idempotency: you generate 2 payments when the first timed out (was 200 OK, just didn't reach back). Use UUID per order.
• Polling /status every 100ms: blows rate limit in seconds. Use webhook.

Public API status

PixGo doesn't have a dedicated status page (like status.pixgo.org) yet. To confirm if an outage is on our side:

• Try accessing pixgo.org/api/v1/docs — if it loads, backend is alive
• Try a POST /payment/create with R$10 via curl — if it returns 201, all OK
• Check our Telegram @PixGoOrg — we announce maintenance and incidents there
• If none works, open a ticket anyway — could be real

Practical summary

• 4xx = your problem (usually quick fix by reading the message)
• 5xx = PixGo problem (retry with backoff, log request_id)
• 429 = you blew through rate limit (use webhook instead of polling)
• Webhook breaking: check HMAC, encoding, timeout, idempotency
• Before ticket: reproduce with curl, capture request+response+timestamp+request_id
• Idempotency keys + retry with exponential backoff = robust integration

Related reading: PixGo API v1 — full guide · Recurrence via API · ChatGPT as integration copilot