Errors

All GoPay APIs return errors in a single, stable shape. code is machine-readable and safe to program against; message is human-readable; requestId identifies the request in GoPay’s logs — include it in support tickets.

{
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "amount must be greater than 0; notifyUrl must use https",
        "requestId": "req_..."
    }
}

Validation errors are accumulated: the message lists every failing field, not just the first, so you can fix all issues in one pass.

Error Codes

Code	HTTP Status	Meaning
`INVALID_REQUEST`	400	Body is not valid JSON or is missing required fields
`VALIDATION_FAILED`	400	One or more fields failed validation; message lists them all
`MISSING_AUTH_HEADERS`	401	One of `X-Public-Key`, `X-Signature`, `X-Timestamp`, `X-Request-ID` is missing
`INVALID_SIGNATURE`	401	Authentication failed (generic — covers bad signature, unknown key, expired key, stale timestamp, and similar)
`UNAUTHORIZED`	401	Not authorized
`PERMISSION_DENIED`	403	Key lacks the required permission (`c2b`/`b2c`) or client IP is not allowlisted
`INSUFFICIENT_FUNDS`	402	Transfers only — merchant wallet balance cannot cover the payout
`IDEMPOTENCY_CONFLICT`	409	`X-Request-ID` was already used (replay / duplicate request)
`RATE_LIMITED`	429	Per-merchant rate limit exceeded
`INTERNAL`	500	Unexpected server error
`UPSTREAM_UNAVAILABLE`	503	A downstream service is temporarily unavailable
`UPSTREAM_TIMEOUT`	504	A downstream call timed out

Authentication failures are deliberately generic. INVALID_SIGNATURE covers every authenticity check — bad signature, unknown or inactive key, merchant mismatch, stale timestamp — so responses never reveal which specific check failed.

Retry Guidance

Payments (C2B) — on UPSTREAM_UNAVAILABLE or UPSTREAM_TIMEOUT, retry with a fresh X-Request-ID and signature (the old ID may already be consumed), and send the same Idempotency-Key so the payment is not created twice. Transfers (B2C) — retrying moves money, so be careful. On a timeout, check for a settlement webhook or contact support with the requestId before resubmitting, and always use a stable client_reference so duplicates surface during reconciliation. The wallet debit itself is idempotent per transaction, so a single accepted transfer can never double-charge. Never retry INVALID_SIGNATURE, PERMISSION_DENIED, or VALIDATION_FAILED without fixing the underlying problem — see Common Mistakes for the usual signature culprits. Back off on RATE_LIMITED (429) before retrying; your per-merchant budget refills over time.

Getting Started

Accept Payments

Make Transfers

Webhooks

Resources

Errors

Errors

Error Codes

Retry Guidance

​Errors

​Error Codes

​Retry Guidance

Errors

Error Codes

Retry Guidance