Errors

Errors use HTTP status codes and a stable code in the body. Act on the code; show the message to people. details names each invalid field.

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "The wallet does not have enough money for this.",
  "request_id": "01JC…"
}

Codes

Status	code	Meaning	What to do
400	VALIDATION_ERROR	A field is missing or invalid (see details), or a write has no Idempotency-Key	Fix the request
401	UNAUTHENTICATED	No key, or not a valid one	Check the key; it may have been revoked
403	FORBIDDEN	The API is off for your organisation, the key may not do this (moving money needs a key that can), or your account is frozen	Use the right key, or contact support
403	IP_NOT_ALLOWED	The key does not work from this address	Call from an allowed address, or change the allow-list
404	NOT_FOUND	No such thing, or it is not yours	Check the ID or reference
409	REFERENCE_USED, REFERENCE_TAKEN	Your reference was already used for something different	Use a new reference, or fetch the existing one
409	IDEMPOTENCY_KEY_REUSED	This Idempotency-Key was used for a different request	Use a new key for a new request
409	IDEMPOTENCY_KEY_IN_USE	The first request with this key is still running	Wait a moment and retry with the same key
422	NOT_LIVE	A live key used before your organisation is live	Go live first
422	LIVE_ONLY	This works only with a live key (withdrawals, payment links)	Use a live key
422	a rule, such as INSUFFICIENT_FUNDS, WALLET_NOT_ACTIVE, WALLET_PROTECTED, IDENTITY_NOT_VERIFIED, NOT_SYNCED, NOT_ACTIVE, MANDATE_ENDED, WALLET_NOT_EMPTY	The request is valid but not allowed now; message says why	Change what the message names, then retry
429	RATE_LIMITED, WITHDRAWAL_TOO_SOON	Too many requests	Wait Retry-After seconds
500	INTERNAL_ERROR	An error on our side	Retry with the same Idempotency-Key
502, 503	BANK_UNAVAILABLE, BUSY	The bank could not be reached, or we are busy	Retry with the same Idempotency-Key after a short wait
503	SANDBOX_NOT_READY	Test keys: your sandbox account is still opening	Retry in a minute
503	MAINTENANCE	CatholicPay is under maintenance	Retry later

Retrying safely

Retry 5xx, 429 and IDEMPOTENCY_KEY_IN_USE with the same Idempotency-Key and back off between attempts (for example 1, 2, 4, 8 seconds). Because the key is the same, a request that did succeed is never done twice: you get its first result. Do not retry other 4xx errors unchanged.

When a payment’s outcome is unclear (a timeout, a lost connection), don’t guess: verify it or fetch it by reference.