Payment Errors

The HellOOpass error shape, the most common API error codes, and when to retry.

Placeholder API contract

Path, headers, and fields below are illustrative until the final HellOOpass API contract is published.

Errors carry an HTTP status plus a JSON body with a stable application code, a human-readable message, and — for validation failures — the offending param.

Error shape

{
  "error": {
    "code": "invalid_request",
    "message": "amount must be a positive integer.",
    "param": "amount"
  }
}

Branch on error.code, not on message — messages may change, codes are stable.

Common errors

HTTP	Code	Action
`400`	`invalid_request`	Fix the field named by `param`; do not retry unchanged.
`401`	`unauthorized`	Check the API key and that it matches the environment.
`403`	`forbidden`	Check key permissions and project status.
`404`	`not_found`	Verify the `payment_id` and environment.
`409`	`conflict`	Reuse the existing payment or supply a new `reference`.
`422`	`business_rule_violation`	Correct the request per `message`.
`429`	`rate_limited`	Back off with jitter; honor `Retry-After` if present.
`5xx`	`server_error`	Retry with backoff and an `Idempotency-Key`.

A call can succeed with 201 Created while the payment itself ends as failed — that is a payment outcome, not an API error.

Reading an error

curl -i https://sandbox-api.helloopass.example/v1/payments/pay_01HZX9K2EXAMPLE \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY"
 
# HTTP/1.1 404 Not Found
# {"error":{"code":"not_found","message":"No payment exists with that id."}}

Retries

Retry 429 and 5xx with exponential backoff plus jitter, always reusing the original Idempotency-Key so a retry cannot create a duplicate payment.
Never retry 4xx unchanged — 400, 401, 403, 404, 409, and 422 fail identically until the request or your credentials change.
404 on payment lookups usually means a wrong identifier or a sandbox versus production mix-up — not a transient condition.

Related: Verify Payment