Errors

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

Error response

{
  "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.
param	Present when a specific request field caused the error.

Tip

Switch on error.code, never on message — messages may change, codes are stable.

Status codes

Status	Meaning	Retryable?
400	Invalid request — malformed body or bad parameters.	No — fix the request.
404	No such payment intent.	No.
409	Invalid state transition (e.g. committing a canceled intent, refunding more than remains, or an intent already processing).	No — reconcile state first.
502	The upstream processor was unreachable or timed out.	Yes — safe to retry.

Declines vs. errors

A declined payment is not an error: it returns a success status with the intent in a failed state. Only the codes above are true errors. See Test mode to reproduce declines.

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.