Errors

Understanding and handling errors from the Uprails API.

Error Response Format

When an error occurs, the API returns a JSON response with an error object containing the error type, code, and a human-readable message.

{
  "error": {
    "type": "invalid_request",
    "code": "IR_04",
    "message": "Invalid value for field: amount"
  }
}

HTTP Status Codes

Error Types

authentication_error

Issues with API authentication. Check that your API key is correct and has the required permissions.

invalid_request

The request was malformed or contained invalid parameters. Check the request body and parameters.

processing_error

An error occurred while processing the payment. This may include card declines or issues with the payment method.

rate_limit_error

Too many requests were made in a short period. Wait and retry with exponential backoff.

api_error

An unexpected error occurred on our servers. These are rare and usually temporary. Retry with exponential backoff.

Common Error Codes

Payment Failure Codes

Every card network and acquirer describes the same decline differently. A payment refused for insufficient funds may come back as INSUFFICIENT_FUNDS, 51, or NotSufficientFunds depending on which acquirer handled it.

unified_code normalises these into one vocabulary, so you can write your decline handling once and it keeps working when we add an acquirer. It appears on the payment object, in /payments/list, and in webhooks.

Response shape

{
  "payment_id": "pay_kQdeYLEIhIk62GZomSsE",
  "status": "failed",
  "unified_code": "UE_1003",
  "unified_message": "The card number is invalid",
  "error_code": "DECLINED",
  "error_message": "Resubmit with alternative payment details",
  "error_details": {
    "unified_details": {
      "category": "UE_1003",
      "message": "The card number is invalid"
    },
    "issuer_details": {
      "code": "14",
      "message": "Invalid card number",
      "network_details": { "name": "Visa" }
    },
    "connector_details": {
      "code": "DECLINED",
      "message": "Resubmit with alternative payment details",
      "reason": "Failed: Invalid card number"
    }
  }
}

unified_code and unified_message are what you should branch on and, where appropriate, show to your customer. error_code, error_message and error_details.connector_details carry the acquirer's own wording — useful when raising a support ticket with us, but they vary by acquirer and are not a stable integration surface.

Code families

The first digit tells you what kind of failure it was, which is usually enough to decide what to do. Match on the family when you want broad handling, on the exact code when you want to tailor the message.

UE_1xxx — Card and issuer declines

The issuer refused the payment. The card details or the account are the problem.

UE_2xxx — Eligibility and risk

The payment was stopped by eligibility or risk rules rather than by a decline on the card itself. UE_2002 is the exception: there the issuer is asking for authentication.

UE_3xxx — Availability

A temporary problem reaching the acquirer or issuer. Safe to retry later.

UE_4xxx — Request data

Something in the request was missing, malformed or no longer valid.

UE_5xxx — Authentication (3DS)

The payment failed during 3-D Secure, before the issuer was asked to authorise it.

Legacy codes

Acquirers we have not yet migrated still return these coarser codes. Unlike the codes above, a legacy code does not imply a single message — UE_1000 alone covers insufficient funds, an expired card, an incorrect security code and several others.

Fallback

Handling declines

const payment = await response.json();if (payment.status === 'failed') {const code = payment.unified_code;// Branch on the family for broad handlingswitch (code?.slice(0, 4)) {  case 'UE_3':    // Temporary — safe to retry with backoff    return scheduleRetry(payment.payment_id);  case 'UE_5':    // Authentication failed; the card may still be fine    return promptRetryAuthentication(payment.unified_message);  case 'UE_4':    // Our request was wrong — do not retry unchanged    return logIntegrationError(payment);  default:    // UE_1xxx / UE_2xxx — ask for another payment method    return showToCustomer(payment.unified_message);}}

Handling Errors

Here's an example of how to handle errors in your code:

try {const response = await fetch('https://api.uprails.com/payments', {  method: 'POST',  headers: {    'Content-Type': 'application/json',    'api-key': 'snd_YOUR_API_KEY'  },  body: JSON.stringify({    amount: 1000,    currency: 'USD',    profile_id: 'YOUR_PROFILE_ID'  })});const data = await response.json();if (!response.ok) {  const { error } = data;  switch (error.type) {    case 'authentication_error':      console.error('Authentication failed:', error.message);      break;    case 'invalid_request':      console.error('Invalid request:', error.message);      break;    case 'processing_error':      console.error('Payment failed:', error.message);      break;    case 'rate_limit_error':      console.error('Rate limited, retrying...');      break;    default:      console.error('An error occurred:', error.message);  }  return;}console.log('Payment succeeded:', data.payment_id);} catch (networkError) {console.error('Network error:', networkError);}

Retry Strategy

For transient errors (5xx status codes and rate limits), implement exponential backoff with jitter:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      // Only retry on 5xx errors and rate limits
      if (error.status < 500 && error.status !== 429) throw error;

      // Exponential backoff with jitter
      const delay = Math.min(1000 * Math.pow(2, i) + Math.random() * 1000, 30000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}