#Errors

PlutoPay uses conventional HTTP status codes and returns one canonical error envelope for every failure — validation, auth, not-found, rate limit, or server error. There is no second shape to special-case.

#The envelope

{
  "error": {
    "type": "validation_error",
    "message": "The amount field is required.",
    "code": "parameter_invalid",
    "param": "amount"
  }
}

type (always) — a coarse category (see below).
message (always) — a human-readable description.
code (when applicable) — a machine-readable code.
param (validation only) — the offending field.

#Status codes

Status	Meaning
`200` / `201`	Success.
`400`	Bad request — the payment processor rejected the call, or the resource is in the wrong state.
`401`	Missing or invalid API key.
`403`	Key valid but not permitted (publishable key on a secret-only endpoint, or an inactive merchant).
`404`	The resource does not exist (or belongs to another merchant).
`422`	Validation error — one or more request parameters were invalid.
`429`	Rate limit exceeded — see Rate limits.
`5xx`	Something went wrong on PlutoPay's side.

#Error types

`type`	When
`authentication_error`	Missing / invalid / revoked / expired key, or inactive merchant.
`validation_error`	A request parameter failed validation (`422`). Includes `param`.
`not_found`	The resource does not exist (`404`).
`rate_limit_error`	Too many requests (`429`).
`invalid_request` / `invalid_state`	The request is well-formed but not allowed in the current state (e.g. refunding a non-refundable charge).
`checkout_error`, `payment_link_error`, `terminal_error`, `refund_error`, …	A downstream operation failed; `message` explains why.
`api_error`	An unexpected server error (`5xx`).

#Handling errors

Retry 429 and 5xx with the same Idempotency-Key — prefer exponential backoff.
Do not blindly retry 4xx validation errors; read message / param, fix the request, and resend.
Branch on error.type for programmatic handling; show error.message to developers.