Errors

All errors share one envelope:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

details is optional; it’s included for validation errors to specify which fields failed. Every response also carries an X-Response-ID header; include it when contacting support@prava.space.

Authentication & validation

These can occur on any endpoint:

Status	Code	Cause	Recovery
401	`AUTH_1001`	Invalid or missing API key	Use `Authorization: Bearer sk_…` with a valid secret key for the right environment
401	`AUTH_1002`	Missing or invalid Authorization header	Include the header exactly as `Bearer sk_…`
401	`AUTH_1003`	Session has expired	Create a new session
401	`AUTH_1004`	Session has been revoked	Create a new session
400	`VAL_2001`	Request failed schema validation	Check `details` for the failing fields
400	`INVALID_REQUEST`	A required field is missing (e.g. `customer_id`, `card_id`)	Include the named field

Create Session — `POST /v1/sessions`

Status	Code	Cause	Recovery
429	`TRIES_EXHAUSTED`	Your account’s session allowance is depleted	Contact support@prava.space
500	`MERCHANT_LOOKUP_ERROR`	Your merchant account couldn’t be resolved	Retry; if persistent, contact support with the `X-Response-ID`
500	`CONFIG_ERROR`	Merchant account is missing payment configuration	Contact support; this is an account-setup issue, not a request problem
400	`CARD_NOT_FOUND`	A pre-selected card doesn’t exist	Verify via List Cards
400	`CARD_INACTIVE`	A pre-selected card is not active	Choose an active card
500	`SESSION_CREATE_ERROR`	Internal failure creating the session	Retry; then support

Payment Result — `GET /v1/sessions/{sessionId}/payment-result`

Quote checkout failures are polling outcomes, so the endpoint still returns HTTP 200 with top-level status: "failed" and may include one of these error.code values.

Status	Code	Cause	Recovery
200	`CARD_DECLINED`	The issuer declined the payment	Ask the cardholder to check with their issuer or use another card
200	`INSUFFICIENT_FUNDS`	The card has insufficient funds	Use another funding source
200	`INVALID_CARD_NUMBER` / `INVALID_SECURITY_CODE` / `INVALID_EXPIRY_DATE`	Card details are invalid	Ask the cardholder to correct the relevant details
200	`EXPIRED_CARD`	The card has expired	Use a valid card
200	`BILLING_DETAILS_MISMATCH`	Billing details could not be verified	Check the billing details
200	`CARD_NOT_SUPPORTED` / `PAYMENT_METHOD_UNAVAILABLE`	The selected payment method cannot be used	Choose another supported payment method
200	`AUTHENTICATION_FAILED`	Payment authentication failed	Review the failure before starting another attempt
200	`PAYMENT_FAILED`	Generic payment failure; no recognized canonical detail is available	Review the result before retrying
200	`MERCHANT_PREPARE_FAILED`	The merchant checkout could not be prepared	Create a fresh quote and session
200	`MERCHANT_ACTION_REQUIRED`	The merchant requires additional verification	Contact support or complete the required merchant action
404	`NOT_FOUND`	Session not found, or it belongs to another merchant	Verify the session ID and which key created it
409	`PAYMENT_RESULT_UNSUPPORTED`	The session is an enrollment-only flow	Use Get Card Enrollment Status

Read canonical failure details from the top-level error. When merchant lifecycle data exists, merchant_res contains only status and optional orderId. For an explicitly simulated sandbox result, the actual failure can appear under observed_result.error while the effective top-level status is completed and merchant_res.status is paid. At session creation, 400 SANDBOX_SIMULATION_NOT_ALLOWED means simulation was requested for production, custom checkout, or mandate setup. Only the exact payment-stage success shape is accepted; malformed shapes return a validation error. See Sandbox simulation.

Shopping checkout errors

Status	Code	Cause	Recovery
422	`DELIVERY_UNAVAILABLE_FOR_ADDRESS`	The merchant cannot deliver the selected items to the supplied address	Ask the shopper to choose another delivery address or item; retrying the same item and address will not help
422	`INVALID_SHIPPING_REGION`	The supplied state or region is unavailable for this merchant checkout	Choose a region accepted by the merchant for the destination address
422	`INVALID_PHONE_NUMBER`	The merchant rejected the buyer’s phone number	Correct the phone number for the destination country before trying again
422	`INVALID_EMAIL`	The merchant rejected the buyer’s email	Use a different `shipping_address.email`
422	`ADDRESS_CORRECTION_REQUIRED`	The merchant requires a state or province to continue	Add or correct the destination state or province
422	`VARIANT_UNAVAILABLE`	A selected item is no longer available	Choose another variant or product
422 / 503	`MERCHANT_CHECKOUT_FAILED`	The merchant checkout could not be completed	Inspect a 422 response before changing the request; retry a retriable 503 later
503	`MERCHANT_CHECKOUT_UNAVAILABLE`	The merchant checkout is temporarily unavailable	Try again later
503	`MERCHANT_RATE_LIMITED`	The merchant is temporarily limiting checkout requests	Retry later; use `Retry-After` when supplied

An apartment or unit-number suggestion is a non-blocking quote warning, ADDRESS_UNIT_CONFIRMATION_SUGGESTED, rather than an error. The shopper can confirm or add a unit number while keeping the quote usable.

Card Enrollment — `POST /v1/sessions/enroll-card` · `GET /v1/sessions/{sessionId}/status`

Status	Code	Cause	Recovery
400	`ENROLL_USER_EMAIL_REQUIRED`	No email was supplied or previously stored for this merchant’s `user_id`	Supply `user_email`
400	`BIN_COUNTRY_NOT_ALLOWED` / `BIN_ISSUER_NOT_ALLOWED`	The card is not eligible for provisioning	Ask the cardholder for another eligible card
404	`NOT_FOUND`	Session not found, or it belongs to another merchant	Verify the session ID, environment, and key
409	`SESSION_STATUS_UNSUPPORTED`	The status endpoint received a payment or another unsupported session	Use that flow’s result endpoint
409	`ENROLLMENT_ACTION_NOT_FOUND`	The enrollment session is missing its linked action	Contact support with the `X-Response-ID`

Failures after a full_enrollment session is created normally use HTTP 200 with the stable status body. When error.retryable is true, the cardholder retries inside the same iframe; the merchant does not call another API or create another session.

Report Status — `POST /v1/sessions/{sessionId}/report-status`

Status	Code	Cause	Recovery
404	`NOT_FOUND`	Session / order / transaction reference not found	Verify the session ID and `txn_ref_id`
400	`INVALID_STATE`	No transaction awaiting a result	It may already be reported, or the cardholder hasn’t finished
400	`MANDATE_EXPIRED`	The mandate has expired	Create a new session
400	`PRODUCT_NOT_FOUND`	Product not found by the given ID	Verify `product_id` / `product_ref_id`
409	`PAYMENT_AMOUNT_MISMATCH`	The reported total or product amount differs from the amount stored for the transaction	Report the exact persisted amount; decimal-equivalent values such as `25` and `25.00` are accepted
409	`QUOTE_PAYMENT_CONFLICT`	The report conflicts with the payment attempt or outcome already bound to the quote	Stop submitting the conflicting report and retrieve the authoritative payment result
502	`VISA_CONFIRMATION_PENDING`	The payment outcome is saved, but card-network confirmation has not completed	Preserve the saved outcome and retry according to your normal reporting policy
502	`VISA_CONFIRMATION_RECONCILIATION_REQUIRED`	Automatic card-network confirmation attempts are exhausted	Preserve the saved outcome and contact support with the `X-Response-ID`; do not submit a different outcome
502	`VISA_CONFIRMATION_FAILED`	Card-network confirmation failed	Retry; then support
500	`REPORT_STATUS_ERROR`	Internal error	Contact support with the `X-Response-ID`

Cards — `GET /v1/listCards` · `POST /v1/deleteCard`

Status	Code	Cause	Recovery
404	`CUSTOMER_NOT_FOUND`	No customer for the given identifier	Verify `customer_id` (the `user_id` you used at session creation)
404	`NOT_FOUND`	Card not found (delete)	Verify `card_id` via List Cards
502	`NETWORK_DELETE_FAILED`	Card-network deletion failed (delete)	Retry

Revoke Session — `POST /v1/sessions/{id}/revoke`

Status	Code	Cause	Recovery
404	`NOT_FOUND`	Session not found	Verify the session ID
400	`INVALID_STATE`	Session not in a revocable state	It may already be completed or expired

Mandates — `/v1/mandates/*`

Mandate routes authenticate with a secret key or an agent Ed25519 signature; a missing/invalid credential returns 401 AUTH_REQUIRED.

Status	Code	Cause	Recovery
401	`AUTH_REQUIRED`	Missing or invalid credentials	Send a valid secret key or agent signature
403	`MANDATE_FORBIDDEN`	The caller doesn’t own this mandate	Act only on mandates owned by the calling agent/merchant
403	`MANDATE_MERCHANT_NOT_ALLOWED`	A charge fell outside a `listed` mandate’s merchant	Charge only at the mandate’s merchant, or use an `any`-scope mandate
404	`MANDATE_NOT_FOUND`	No mandate with that id for the caller	Verify the mandate id via List Mandates
409	`MANDATE_NOT_ACTIVE`	Charged a mandate that isn’t `active` (e.g. paused, consumed, expired)	Resume it, or set up a new mandate
409	`MANDATE_INVALID_TRANSITION`	An illegal lifecycle change (e.g. resume a cancelled mandate)	Only pause `active`, resume `paused`, cancel `active`/`paused`
409	`NO_INSTRUCTION` / `NO_ORDER`	The mandate is missing its underlying instruction/order (charge)	Re-run mandate setup
500	`NO_TOKEN`	Credential minting failed (charge)	Retry; then support

Reporting a charge (/charges/{txnId}/report) can additionally return 404 CHARGE_NOT_FOUND, 409 CHARGE_NOT_REPORTABLE / CHARGE_NO_TLI, 502 VISA_CONFIRMATION_FAILED, or 500 MANDATE_CHARGE_REPORT_DB_FAILED.

THRESHOLD_EXCEEDED is not a Prava error code — it’s a Visa decline (an over-cap charge) surfaced in a failed charge’s errorCode / errorMessage, not in the error envelope. See Charge a Mandate.

The SDK has its own client-side error codes (SDK_ALREADY_ACTIVE, INVALID_CONFIG, IFRAME_LOAD_ERROR, SDK_INIT_ERROR); see Collect Card Details. CLI errors are mapped on the Prava Pay troubleshooting page.

Server-Side API

Reference

Authentication & validation

Create Session — `POST /v1/sessions`

Payment Result — `GET /v1/sessions/{sessionId}/payment-result`

Shopping checkout errors

Card Enrollment — `POST /v1/sessions/enroll-card` · `GET /v1/sessions/{sessionId}/status`

Report Status — `POST /v1/sessions/{sessionId}/report-status`

Cards — `GET /v1/listCards` · `POST /v1/deleteCard`

Revoke Session — `POST /v1/sessions/{id}/revoke`

Mandates — `/v1/mandates/*`

​Authentication & validation

​Create Session — POST /v1/sessions

​Payment Result — GET /v1/sessions/{sessionId}/payment-result

​Shopping checkout errors

​Card Enrollment — POST /v1/sessions/enroll-card · GET /v1/sessions/{sessionId}/status

​Report Status — POST /v1/sessions/{sessionId}/report-status

​Cards — GET /v1/listCards · POST /v1/deleteCard

​Revoke Session — POST /v1/sessions/{id}/revoke

​Mandates — /v1/mandates/*

Authentication & validation

Create Session — `POST /v1/sessions`

Payment Result — `GET /v1/sessions/{sessionId}/payment-result`

Shopping checkout errors

Card Enrollment — `POST /v1/sessions/enroll-card` · `GET /v1/sessions/{sessionId}/status`

Report Status — `POST /v1/sessions/{sessionId}/report-status`

Cards — `GET /v1/listCards` · `POST /v1/deleteCard`

Revoke Session — `POST /v1/sessions/{id}/revoke`

Mandates — `/v1/mandates/*`