Reference
Errors
Pay-Pi returns errors as application/problem+json (RFC 7807). Every error
carries a type URI (which links to the matching entry on this page), a
human-readable title and detail, the HTTP status,
and a traceId you can quote when contacting support.
Shape
{
"type": "https://pay-pi.com/docs/errors#finix",
"title": "Payment provider error",
"status": 502,
"detail": "Your card was declined.",
"traceId": "0HN7A2K9C4E1"
}Catalog
Each error type resolves to an anchor below.
The merchant account cannot accept payments yet. Onboarding is incomplete, the application is still under review, or charges are disabled. Check the account readiness (onboarding status, charges enabled) and complete any outstanding requirements before retrying.
The upstream payment provider (Finix) returned an error while processing the request — for example a declined card or a provider-side validation failure. The human-readable reason is in the detail field. These are generally safe to surface to the buyer and, for declines, to retry with a different instrument.
The API key is missing, malformed, or revoked. Send a valid secret key (lc_live_…) in the X-Api-Key header. Manage keys from your dashboard.
The request was well-formed but a field failed validation (for example a missing amount or an unsupported currency). The detail field names the problem; fix the request and retry.
The referenced resource (payment, payout, or merchant) does not exist or is not visible to your API key.
You have exceeded the request rate limit. Back off and retry using the Retry-After response header.