Error Handling

Handle payment errors gracefully to give customers a smooth experience.

Error Response Format

All API errors follow this structure:

{
  "success": false,
  "error": "Human-readable error message",
  "details": ["Specific validation error 1", "Specific validation error 2"]
}

HTTP Status Codes

Code	Meaning	What to Do
`400`	Bad Request	Check your request parameters
`401`	Unauthorized	Verify your API keys
`404`	Not Found	Session doesn’t exist
`409`	Conflict	Session already completed/cancelled
`410`	Gone	Session expired
`429`	Too Many Requests	The API key check was throttled (`errorCode: "VAULT_RATE_LIMITED"`). Your key is not the problem: wait `Retry-After` seconds, then retry
`500`	Server Error	Retry the request
`502`	Bad Gateway	Upstream service unavailable — retry with backoff
`503`	Service Unavailable	Service temporarily down, or the API key check couldn’t be completed (`errorCode: "VAULT_UNAVAILABLE"`) — retry with backoff

Two Types of Errors

Ozura Checkout handles errors differently based on whether the customer can fix them:

Fixable Errors (Customer Stays on Checkout)

These errors allow the customer to try again without leaving the checkout page:

Card declined
Insufficient funds
Invalid card number
Expired card
Wrong CVV
Address verification failed

What happens: An inline error message appears. The customer can correct their information and try again.

Unrecoverable Errors (Redirect to errorUrl)

These errors require redirecting the customer away from checkout:

Server/system errors
Authentication failures
Network connectivity issues
Payment processor unavailable

What happens: The customer is redirected to your errorUrl with error details in the URL.

Redirect Behavior Summary

Situation	What Happens	Session Status
Payment successful	Redirect to `successUrl`	`completed`
Fixable error (card declined)	Stays on checkout – inline error	`pending`
Unrecoverable error	Redirect to `errorUrl`	`failed`
Customer cancels	Redirect to `cancelUrl`	`cancelled`
Session expires	Ozura expiration page → `cancelUrl`	`expired`

Error URL Parameters

When an unrecoverable error occurs, the customer is redirected to your errorUrl:

https://yoursite.com/error?success=false&errorCode=SYSTEM_ERROR&error=Payment+service+unavailable&cancelUrl=https://yoursite.com/cart

Parameter	Description	Example
`success`	Always `false`	`false`
`errorCode`	Machine-readable error type	`SYSTEM_ERROR`, `SESSION_FAILED`
`error`	Human-readable message	`Payment service unavailable`
`cancelUrl`	Your cancelUrl (for “return” navigation)	`https://yoursite.com/cart`

Error Codes

Code	Meaning
`SYSTEM_ERROR`	Server or connectivity issue
`SESSION_FAILED`	Session marked as failed
`MANUAL_REVIEW`	Transaction flagged for manual review
`FORBIDDEN`	Too many failed payment attempts

Building Your Error Page

// Parse URL parameters
const params = new URLSearchParams(window.location.search);
const errorCode = params.get('errorCode');
const errorMessage = params.get('error');
const returnUrl = params.get('cancelUrl');

// Display to user
document.getElementById('error-message').textContent = 
  errorMessage || 'Something went wrong. Please try again.';

// Set up return button
if (returnUrl) {
  document.getElementById('return-btn').href = returnUrl;
}

Recommended Approach: Redirect to Cart with Message

Instead of showing a dead-end error page, redirect customers back to their cart with a popup message: Set your errorUrl to your cart page with a flag:

errorUrl: "https://yoursite.com/cart?showError=true"

Then on your cart page:

const params = new URLSearchParams(window.location.search);
if (params.get('showError')) {
  const errorMessage = params.get('error') || 'Something went wrong during checkout';
  showErrorPopup(errorMessage);
  
  // Clean up URL
  window.history.replaceState({}, '', '/cart');
}

This keeps customers in their shopping flow instead of showing a confusing error page.

Retry Logic for API Calls

It’s safe to retry a 429 (after its Retry-After delay) and a 5xx error. Don’t retry other 4xx errors: they mean the request itself needs fixing. Send an idempotencyKey (see Network Retry Protection), so that a retry after a lost response returns the original session instead of creating a second one.

async function createSessionWithRetry(data, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    let response;
    try {
      response = await fetch('https://checkout.ozura.com/api/sessions/create', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-KEY': process.env.VAULT_API_KEY,
          'X-OZURA-API-KEY': process.env.MERCHANT_API_KEY
        },
        body: JSON.stringify(data) // include an idempotencyKey
      });
    } catch (networkError) {
      // No response at all: retry with backoff
      if (attempt === maxRetries) throw networkError;
      await new Promise(r => setTimeout(r, 1000 * attempt));
      continue;
    }

    if (response.ok) {
      return await response.json();
    }

    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt === maxRetries) {
      // Other 4xx: fix the request (see the error message) instead of retrying
      throw new Error(`Request failed: ${response.status}`);
    }

    // 429: wait as long as Retry-After says; otherwise exponential backoff
    const retryAfter = Number(response.headers.get('Retry-After'));
    const delayMs = response.status === 429 && retryAfter > 0 ? retryAfter * 1000 : 1000 * attempt;
    await new Promise(r => setTimeout(r, delayMs));
  }
}

Network Retry Protection

To prevent duplicate sessions from network issues, use an idempotency key:

{
  "merchantId": "your_merchant_id",
  "merchantName": "My Store",
  "amount": "25.00",
  "idempotencyKey": "order_12345"
}

If you send the same idempotencyKey twice, you’ll get back the original session instead of creating a duplicate (the response will include "cached": true). If the original session has expired or reached a terminal state (cancelled / failed), the replay is rejected with a 409 and one of these errorCode values — use a new idempotencyKey to create a fresh session:

`errorCode`	Meaning
`IDEMPOTENCY_KEY_EXPIRED_SESSION`	The session created with this key has expired
`IDEMPOTENCY_KEY_TERMINAL_SESSION`	The session created with this key is `cancelled` or `failed`

Getting Started

Vault

Payments

Error Handling

Error Response Format

HTTP Status Codes

Two Types of Errors

Fixable Errors (Customer Stays on Checkout)

Unrecoverable Errors (Redirect to errorUrl)

Redirect Behavior Summary

Error URL Parameters

Error Codes

Building Your Error Page

Recommended Approach: Redirect to Cart with Message

Retry Logic for API Calls

Network Retry Protection

​Error Response Format

​HTTP Status Codes

​Two Types of Errors

​Fixable Errors (Customer Stays on Checkout)

​Unrecoverable Errors (Redirect to errorUrl)

​Redirect Behavior Summary

​Error URL Parameters

​Error Codes

​Building Your Error Page

​Recommended Approach: Redirect to Cart with Message

​Retry Logic for API Calls

​Network Retry Protection

Error Response Format

HTTP Status Codes

Two Types of Errors

Fixable Errors (Customer Stays on Checkout)

Unrecoverable Errors (Redirect to errorUrl)

Redirect Behavior Summary

Error URL Parameters

Error Codes

Building Your Error Page

Recommended Approach: Redirect to Cart with Message

Retry Logic for API Calls

Network Retry Protection