Errors

Standard HTTP error codes and formats.

The API returns standard HTTP status codes. Errors include a JSON body with an error field.

Status codes

Code	type	Meaning
400	invalid_request_error	Bad request — invalid or missing parameters
401	authentication_error	Missing or invalid API key
402	card_error	Payment failed — charge was declined
403	permission_error	Secret key required for this endpoint
404	not_found_error	Resource doesn't exist
409	idempotency_error	Conflict — resource or idempotency key reused
429	rate_limit_error	Too many requests
5xx	api_error	Something went wrong on Paysio's side

Error response format

Branch on type rather than the error sentence — the wording may change, the category will not.

JSON

{
  "error": "Customer not found",   // human-readable (wording may change)
  "type": "not_found_error",       // stable category — branch on this
  "code": "resource_missing"       // specific code where one applies
}

Failed charges

A charge that is declined (402) or that could not be completed (503) carries extra fields naming the cause, so you do not have to parse the error sentence.

JavaScript

// Failed charge — POST /v1/charges
{
  "error": "Charge declined: Insufficient funds (202)",
  "code": "insufficient_funds",     // stable Paysio code — branch on this
  "decline_code": "202",            // the gateway's own code, verbatim
  "category": "insufficient_funds", // see the table below
  "reference_id": "8134729",        // quote this to support
  "data": { /* the transaction record */ }
}

Decline categories

category	What to do
declined	The issuer said no. Ask for a different card; retrying the same one will not help.
insufficient_funds	Ask for a different card.
invalid_card	The number or expiry is wrong. Ask the customer to re-enter it.
cvc	The security code is missing or wrong. Collect it again.
unsupported_card	This card type cannot be used on this workspace's gateway (e.g. a credit card on a debit-only rail).
duplicate	The gateway matched a recent identical attempt. Wait before retrying.
configuration	A problem with the merchant account, not the card. Contact support with the reference_id.
gateway_unavailable	Returned with 503. The outcome is not yet known, so do not assume the charge failed — retry with the same reference_id, which is refused if the first attempt is still unresolved.
unknown	We could not classify it. Read `error` and quote the reference_id.

The status code separates the two failure kinds: 402 is a definite failure (no money moved — safe to retry with a new reference_id once the customer fixes it), 503 is an unknown outcome (retry with the same reference_id). A card rejected before the charge is attempted returns 402, so an unusable card no longer looks like an outage.