Errors

When a request fails, Paygasus Pay returns a consistent JSON envelope alongside a standard HTTP status code.

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_exceeds_refundable",
    "message": "Refund amount exceeds the remaining refundable balance.",
    "param": "amount"
  }
}

Field	Description
`type`	Broad category of the error.
`code`	Stable, machine-readable identifier. Branch on this.
`message`	Human-readable explanation. Do not parse it, Paygasus will not guarantee this as a stable field against breaking changes.
`param`	Present when a specific request field caused the error.

Status codes

Status	Meaning	Retryable?
`400`	Invalid request, malformed body or bad parameters.	No, fix the request.
`401`	Missing, invalid, or revoked API key. See Authentication.	No, fix the credential.
`404`	No such payment intent, including one belonging to another merchant, or a live intent requested with a test key.	No.
`409`	Invalid state transition (e.g. committing a canceled intent, refunding more than remains, or an intent already processing).	No, reconcile state first.
`422`	Well-formed, but not processable, e.g. your merchant account has no processor configuration for this mode.	No, contact support.
`502`	The upstream processor was unreachable or timed out.	Yes, safe to retry.

Retrying safely

502 responses mean the request may not have reached the processor. Retry with the same parameters; combine with idempotency where available so a retry can’t double-charge.