Version: 2019-05-29 (Current)

Error Handling

Understand Omise API errors and implement robust error handling for reliable payment integrations. Learn about HTTP status codes, error response formats, and best practices for debugging.

Overview

The Omise API uses conventional HTTP response codes to indicate the success or failure of an API request. Errors return JSON-encoded responses with detailed information to help you debug and handle failures gracefully.

Quick Reference

2xx codes → Success
4xx codes → Client errors (your request was invalid)
5xx codes → Server errors (something went wrong on Omise's side)
All errors return JSON with object: "error" and descriptive fields

Error Response Format

All API errors return a consistent JSON structure:

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#authentication-failure",
  "code": "authentication_failure",
  "message": "authentication failed"
}

Error Object Fields

Field	Type	Description
`object`	string	Always `"error"` for error responses
`location`	string	URL to documentation for this error type
`code`	string	Machine-readable error code (lowercase with underscores)
`message`	string	Human-readable error message in English

Additional Fields

Some errors may include additional context-specific fields like charge_id, customer_id, or validation_errors for detailed debugging.

HTTP Status Codes

2xx Success

200 OK

Meaning: Request succeeded

{
  "object": "charge",
  "id": "chrg_test_5xuy4w91xqz7d1w9u0t",
  "amount": 100000,
  "status": "successful"
}

When it occurs:

✅ GET requests returned data successfully
✅ POST/PATCH requests completed successfully
✅ DELETE requests removed resource successfully

201 Created

Meaning: Resource created successfully

When it occurs:

✅ POST request created a new resource (rare, usually returns 200)

4xx Client Errors

Client errors indicate problems with the request you sent. Fix the request and retry.

400 Bad Request

Meaning: The request was malformed or contains invalid parameters

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#bad-request",
  "code": "bad_request",
  "message": "amount must be at least 2000 (in subunits)"
}

Common causes:

❌ Missing required parameters
❌ Invalid parameter values
❌ Amount below minimum threshold
❌ Unsupported currency
❌ Malformed JSON payload
❌ Invalid parameter types

Example scenarios:

# Missing required parameter
curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_...: \
  -d "currency=thb"
# Error: amount is required

# Amount too small
curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_...: \
  -d "amount=100" \
  -d "currency=thb"
# Error: amount must be at least 2000 (20 THB)

How to fix:

✅ Check API documentation for required parameters
✅ Validate parameter values before sending
✅ Ensure proper data types (numbers as numbers, not strings)
✅ Verify currency-specific minimum amounts

401 Unauthorized

Meaning: Authentication failed - invalid or missing API key

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#authentication-failure",
  "code": "authentication_failure",
  "message": "authentication failed"
}

Common causes:

❌ No API key provided
❌ Invalid API key format
❌ Revoked or expired API key
❌ Wrong key for environment (test key in production)
❌ API key not properly encoded in Authorization header

Example scenarios:

# Missing API key
curl https://api.omise.co/account
# Error: authentication failed

# Invalid API key
curl https://api.omise.co/account \
  -u invalid_key:
# Error: authentication failed

# Using public key for secret key operation
curl https://api.omise.co/charges \
  -X POST \
  -u pkey_test_...: \
  -d "amount=100000" \
  -d "currency=thb"
# Error: authentication failed

How to fix:

✅ Verify API key is correct (copy from Dashboard)
✅ Check for extra spaces or characters
✅ Use secret key for server-side operations
✅ Use public key only for tokens/sources
✅ Ensure key hasn't been revoked
✅ Verify test vs live key matches environment

Learn more about Authentication →

402 Payment Required

Meaning: Card or payment method was declined

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#payment-declined",
  "code": "payment_declined",
  "message": "Your card was declined",
  "charge_id": "chrg_test_5xuy4w91xqz7d1w9u0t"
}

Common causes:

❌ Insufficient funds
❌ Card expired
❌ Incorrect card details (CVV, expiry)
❌ Card issuer declined (fraud suspicion)
❌ Card not enabled for online payments
❌ Transaction limit exceeded

Payment-specific error codes:

Code	Meaning	Action
`insufficient_fund`	Not enough money on card	Ask customer to use different card
`invalid_card`	Card number invalid	Verify card number
`stolen_or_lost_card`	Card reported stolen/lost	Ask customer to contact bank
`failed_processing`	Processing failed	Retry or use different card
`payment_cancelled`	Customer cancelled payment	Customer action, no fix needed
`payment_expired`	Payment window expired	Create new charge

Example scenario:

# Charge attempt with insufficient funds
curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_...: \
  -d "amount=1000000" \
  -d "currency=thb" \
  -d "card=tokn_test_..."
# Error: insufficient_fund

How to fix:

✅ Show clear error message to customer
✅ Ask customer to try different payment method
✅ Don't retry same card multiple times (avoid card blocks)
✅ Suggest customer contacts their bank
✅ Log decline reason for analysis

Don't Retry Payment Failures

Repeatedly attempting declined cards can trigger fraud alerts and get cards blocked. Instead, ask customers to verify their payment details or use an alternative payment method.

404 Not Found

Meaning: The requested resource doesn't exist

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#not-found",
  "code": "not_found",
  "message": "charge chrg_test_invalid was not found"
}

Common causes:

❌ Invalid resource ID
❌ Resource was deleted
❌ Wrong API endpoint URL
❌ Typo in resource ID
❌ Using test ID in live mode (or vice versa)

Example scenarios:

# Invalid charge ID
curl https://api.omise.co/charges/chrg_invalid \
  -u skey_test_...:
# Error: not found

# Wrong endpoint
curl https://api.omise.co/charge/chrg_test_... \
  -u skey_test_...:
# Error: not found (should be /charges not /charge)

How to fix:

✅ Verify resource ID is correct
✅ Check resource wasn't deleted
✅ Ensure test/live mode matches key
✅ Verify endpoint URL spelling
✅ Search for resource using list endpoint

422 Unprocessable Entity

Meaning: Request was well-formed but contains semantic errors

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#invalid-charge",
  "code": "invalid_charge",
  "message": "charge has already been captured"
}

Common causes:

❌ Attempting invalid state transition
❌ Business logic violation
❌ Resource already processed
❌ Invalid parameter combination

Example scenarios:

# Capturing already-captured charge
curl https://api.omise.co/charges/chrg_test_.../capture \
  -X POST \
  -u skey_test_...:
# Error: charge has already been captured

# Refunding more than charge amount
curl https://api.omise.co/charges/chrg_test_.../refunds \
  -X POST \
  -u skey_test_...: \
  -d "amount=200000"
# Error: refund amount exceeds available amount

How to fix:

✅ Check resource state before operations
✅ Verify business logic constraints
✅ Don't retry same operation (it may have succeeded)
✅ Retrieve resource to check current state

429 Too Many Requests

Meaning: You've exceeded rate limits

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#rate-limit-exceeded",
  "code": "rate_limit_exceeded",
  "message": "too many requests, please try again later"
}

Response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1612137600
Retry-After: 60

How to fix:

✅ Implement exponential backoff
✅ Check Retry-After header
✅ Reduce request frequency
✅ Batch operations where possible
✅ Cache responses when appropriate

Learn more about Rate Limiting →

5xx Server Errors

Server errors indicate problems on Omise's side. These are rare but should be handled gracefully.

500 Internal Server Error

Meaning: Something went wrong on Omise's servers

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#internal-server-error",
  "code": "internal_server_error",
  "message": "An internal server error occurred"
}

When it occurs:

⚠️ Unexpected server-side error
⚠️ Temporary service disruption
⚠️ Database connectivity issues

How to handle:

✅ Retry request with exponential backoff
✅ Check status.omise.co for incidents
✅ Contact support if persists
✅ Log error details for debugging

503 Service Unavailable

Meaning: Service is temporarily unavailable

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#service-unavailable",
  "code": "service_unavailable",
  "message": "Service temporarily unavailable"
}

When it occurs:

⚠️ Scheduled maintenance
⚠️ Service overload
⚠️ Upstream provider issues

How to handle:

✅ Retry after delay (check Retry-After header)
✅ Show maintenance message to users
✅ Queue requests for later processing
✅ Check status page

Complete Error Code Reference

400 Bad Request

Code	Message	Description
`backend_error`	"backend error"	Communication failure with payment provider
`bad_request`	"bad request"	Invalid request parameters
`brand_not_supported`	"brand not supported"	Card brand not accepted by account
`documents_locked`	"documents list cannot be modified"	Dispute no longer open for file uploads
`expired_charge`	"charge expired"	Authorization window exceeded or payment code expired
`failed_capture`	"capture failed"	Charge capture unsuccessful
`failed_expire`	"expire failed"	Unable to set charge expiration
`failed_fraud_check`	"fraud check failed"	Card flagged as fraudulent
`failed_multi_currency`	"the currency conversion could not be completed"	Multi-currency conversion error
`failed_refund`	"refund failed"	Refund processing error
`failed_reverse`	"reverse failed"	Charge reversal unsuccessful
`failed_void`	"void failed"	Charge void operation unsuccessful
`feature_not_supported`	"feature not supported"	Account lacks feature access
`invalid_amount`	"invalid amount"	Non-integer amount submitted
`invalid_bank_account`	"invalid bank account"	Bank account details invalid
`invalid_card`	"invalid card"	Card token creation failed
`invalid_card_token`	"invalid card token"	Non-string token object supplied
`invalid_charge`	"invalid charge"	Charge fails minimum requirements
`invalid_dispute`	"invalid dispute"	Dispute modification outside parameters
`invalid_domain`	"request must be made with the vault.omise.co domain"	Incorrect domain for token generation
`invalid_file_type`	"invalid content-type"	Unsupported file type uploaded
`invalid_link`	"invalid link"	Link missing currency or description
`invalid_recipient`	"invalid recipient"	Recipient invalid or nonexistent
`invalid_transfer`	"invalid transfer"	Transfer creation/update error
`missing_card`	"request contains no card parameters"	Card parameters absent in request
`missing_file`	"missing file or filename"	File upload without file content
`used_token`	"token was already used"	Single-use token reused

401 Unauthorized

Code	Message	Description
`authentication_failure`	"authentication failed"	Invalid or missing API key

402 Payment Required

Code	Message	Description
`insufficient_fund`	"insufficient funds"	Not enough money on card
`invalid_card`	"invalid card"	Card number invalid
`stolen_or_lost_card`	"stolen or lost card"	Card reported stolen/lost
`failed_processing`	"processing failed"	Processing failed
`payment_cancelled`	"payment cancelled"	Customer cancelled payment
`payment_expired`	"payment expired"	Payment window expired
`payment_rejected`	"payment rejected"	Payment was rejected

403 Forbidden

Code	Message	Description
`key_expired_error`	"expired key"	API key has expired
`locked_account_error`	"account locked"	Account has been locked
`not_authorized`	"not authorized"	Operation not permitted for this key

404 Not Found

Code	Message	Description
`not_found`	"the requested object was not found"	Resource doesn't exist
`serializer_not_found`	"your current API version does not support this action"	API version incompatibility
`service_not_found`	"you are using an api version that does not support this operation"	Operation not supported in API version

422 Unprocessable Entity

Code	Message	Description
`failed_deletion`	"this object could not be deleted"	Deletion operation failed
`invalid_filter`	"invalid filters"	Invalid search/list filters
`invalid_page`	"invalid page"	Invalid pagination page number
`invalid_per_page`	"invalid per page"	Invalid items per page value
`invalid_scope`	"invalid scope"	Invalid search scope

429 Too Many Requests

Code	Message	Description
`too_many_requests`	"you have sent too many requests in too little time"	Rate limit exceeded

500 Internal Server Error

Code	Message	Description
`internal_error`	"request could not be completed due to an internal error"	Server-side error

503 Service Unavailable

Code	Message	Description
`search_unavailable`	"search is temporarily unavailable"	Search service temporarily down

Error Codes by Category

Authentication Errors

Code	HTTP Status	Description	Solution
`authentication_failure`	401	Invalid or missing API key	Verify API key is correct
`key_expired_error`	403	API key has expired	Generate new API key from Dashboard
`locked_account_error`	403	Account has been locked	Contact support
`not_authorized`	403	Operation not permitted	Use correct key type (public/secret)

Request Errors

Code	HTTP Status	Description	Solution
`bad_request`	400	Invalid request parameters	Check required parameters and formats
`invalid_amount`	400	Non-integer amount	Use integer amount in smallest unit
`invalid_card_token`	400	Invalid token format	Ensure token is a string
`invalid_domain`	400	Wrong domain for request	Use vault.omise.co for tokens
`missing_card`	400	Missing card parameters	Include card or token in request
`used_token`	400	Token already used	Tokens are single-use, create new one
`invalid_charge`	422	Charge state doesn't allow operation	Verify charge status first
`not_found`	404	Resource doesn't exist	Verify resource ID

Payment Errors

Code	HTTP Status	Description	Solution
`insufficient_fund`	402	Not enough balance	Request different payment method
`invalid_card`	400/402	Card details invalid	Verify card number and CVV
`stolen_or_lost_card`	402	Card reported stolen/lost	Customer must contact bank
`failed_processing`	402	Payment processing failed	Retry or use different card
`failed_fraud_check`	400	Card flagged as fraudulent	Customer must contact bank
`payment_cancelled`	402	Customer cancelled payment	Customer action
`payment_expired`	402	Payment window expired	Create new charge
`expired_charge`	400	Authorization expired	Create new charge
`brand_not_supported`	400	Card brand not supported	Use supported card brand

Operation Errors

Code	HTTP Status	Description	Solution
`failed_capture`	400	Capture failed	Check charge state, may be already captured
`failed_refund`	400	Refund failed	Check charge state and refundable amount
`failed_reverse`	400	Reversal failed	Check charge state
`failed_void`	400	Void failed	Check charge state
`failed_expire`	400	Expire failed	Check charge state
`failed_deletion`	422	Deletion failed	Resource may have dependencies

Transfer/Recipient Errors

Code	HTTP Status	Description	Solution
`invalid_bank_account`	400	Invalid bank account	Verify bank account details
`invalid_recipient`	400	Invalid recipient	Verify recipient exists and is active
`invalid_transfer`	400	Invalid transfer	Check transfer parameters

Dispute Errors

Code	HTTP Status	Description	Solution
`invalid_dispute`	400	Invalid dispute operation	Check dispute state
`documents_locked`	400	Cannot modify documents	Dispute is closed
`invalid_file_type`	400	Invalid file type	Use supported file formats
`missing_file`	400	File missing	Include file in upload

System Errors

Code	HTTP Status	Description	Solution
`internal_error`	500	Server-side error	Retry with backoff
`backend_error`	400	Payment provider error	Retry or contact support
`search_unavailable`	503	Search service down	Wait and retry
`too_many_requests`	429	Rate limit exceeded	Implement rate limiting
`feature_not_supported`	400	Feature not enabled	Contact support to enable
`failed_multi_currency`	400	Currency conversion failed	Check currency support

Error Handling Best Practices

1. Always Check HTTP Status First

# ✅ Good - Check status code
require 'omise'

begin
  charge = Omise::Charge.create({
    amount: 100000,
    currency: 'thb',
    card: params[:token]
  })

  # Success
  render json: charge

rescue Omise::Error => e
  # Handle error based on type
  case e.http_status
  when 400
    render json: { error: 'Invalid request' }, status: 400
  when 401
    render json: { error: 'Authentication failed' }, status: 401
  when 402
    render json: { error: 'Payment declined', code: e.code }, status: 402
  when 404
    render json: { error: 'Resource not found' }, status: 404
  when 422
    render json: { error: 'Invalid operation', message: e.message }, status: 422
  when 429
    render json: { error: 'Rate limit exceeded' }, status: 429
  when 500, 503
    render json: { error: 'Service temporarily unavailable' }, status: 503
  else
    render json: { error: 'An error occurred' }, status: 500
  end
end

2. Parse Error Details

# ✅ Good - Extract error details
import omise

try:
    charge = omise.Charge.create(
        amount=100000,
        currency='thb',
        card=token
    )
    return charge

except omise.errors.BaseError as e:
    error_code = e.code
    error_message = e.message

    # Log for debugging
    logger.error(f"Charge failed: {error_code} - {error_message}")

    # Return user-friendly message
    if error_code == 'insufficient_fund':
        return {'error': 'Insufficient funds. Please try a different card.'}
    elif error_code == 'invalid_card':
        return {'error': 'Invalid card details. Please check and try again.'}
    else:
        return {'error': 'Payment failed. Please try again.'}

3. Implement Retry Logic for Server Errors

// ✅ Good - Retry with exponential backoff
const omise = require('omise')({ secretKey: process.env.OMISE_SECRET_KEY });

async function createChargeWithRetry(chargeData, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const charge = await omise.charges.create(chargeData);
      return { success: true, charge };

    } catch (error) {
      const isServerError = error.statusCode >= 500;
      const isLastAttempt = attempt === maxRetries - 1;

      if (isServerError && !isLastAttempt) {
        // Exponential backoff: 1s, 2s, 4s
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      // Don't retry client errors or last attempt
      return {
        success: false,
        error: {
          code: error.code,
          message: error.message,
          statusCode: error.statusCode
        }
      };
    }
  }
}

4. Validate Before Sending Requests

<?php
// ✅ Good - Validate before API call

function createCharge($amount, $currency, $token) {
    // Validate amount
    $minAmounts = [
        'thb' => 2000,  // 20 THB
        'jpy' => 50,    // 50 JPY
        'sgd' => 100,   // 1 SGD
    ];

    if ($amount < $minAmounts[$currency]) {
        return [
            'error' => 'Amount below minimum for ' . strtoupper($currency),
            'min_amount' => $minAmounts[$currency]
        ];
    }

    // Validate currency
    $supportedCurrencies = ['thb', 'jpy', 'sgd', 'myr', 'usd'];
    if (!in_array($currency, $supportedCurrencies)) {
        return [
            'error' => 'Unsupported currency',
            'supported' => $supportedCurrencies
        ];
    }

    // Validate token format
    if (!preg_match('/^tokn_test_[a-z0-9]+$/', $token) &&
        !preg_match('/^tokn_[a-z0-9]+$/', $token)) {
        return ['error' => 'Invalid token format'];
    }

    try {
        $charge = OmiseCharge::create([
            'amount' => $amount,
            'currency' => $currency,
            'card' => $token
        ]);

        return ['success' => true, 'charge' => $charge];

    } catch (Exception $e) {
        return [
            'error' => $e->getMessage(),
            'code' => $e->getCode()
        ];
    }
}

5. Show User-Friendly Messages

// ✅ Good - Translate error codes to user messages
package main

import (
    "github.com/omise/omise-go"
)

func getUserMessage(err error) string {
    if omiseErr, ok := err.(*omise.Error); ok {
        switch omiseErr.Code {
        case "authentication_failure":
            return "A system error occurred. Please try again later."
        case "insufficient_fund":
            return "Your card has insufficient funds. Please use a different card."
        case "invalid_card":
            return "The card details are invalid. Please check and try again."
        case "stolen_or_lost_card":
            return "This card cannot be used. Please contact your bank."
        case "payment_cancelled":
            return "Payment was cancelled. You can try again when ready."
        case "payment_expired":
            return "Payment session expired. Please start a new payment."
        case "rate_limit_exceeded":
            return "Too many attempts. Please wait a moment and try again."
        case "service_unavailable":
            return "Payment service is temporarily unavailable. Please try again later."
        default:
            return "Payment failed. Please try again or use a different payment method."
        }
    }
    return "An unexpected error occurred. Please try again."
}

func createCharge(amount int64, currency string, token string) (string, error) {
    client, _ := omise.NewClient(
        os.Getenv("OMISE_PUBLIC_KEY"),
        os.Getenv("OMISE_SECRET_KEY"),
    )

    charge, err := client.CreateCharge(&omise.ChargeParams{
        Amount:   amount,
        Currency: currency,
        Card:     token,
    })

    if err != nil {
        userMessage := getUserMessage(err)
        return userMessage, err
    }

    return "Payment successful!", nil
}

6. Log Errors for Debugging

# ✅ Good - Comprehensive error logging
require 'logger'

logger = Logger.new('omise_errors.log')

begin
  charge = Omise::Charge.create({
    amount: 100000,
    currency: 'thb',
    card: token
  })

rescue Omise::Error => e
  # Log detailed error information
  logger.error({
    timestamp: Time.now.iso8601,
    error_type: 'omise_api_error',
    http_status: e.http_status,
    error_code: e.code,
    error_message: e.message,
    request_id: e.request_id,
    charge_params: {
      amount: 100000,
      currency: 'thb',
      token: token[0..10] + '...' # Partial token for security
    },
    backtrace: e.backtrace.first(5)
  }.to_json)

  # Re-raise or handle
  raise
end

7. Don't Expose Sensitive Error Details

// ❌ Bad - Exposes internal details
app.post('/charge', async (req, res) => {
  try {
    const charge = await omise.charges.create(req.body);
    res.json(charge);
  } catch (error) {
    // DON'T DO THIS - Exposes API key, internal paths, etc.
    res.status(500).json({ error: error.toString() });
  }
});

// ✅ Good - Safe error messages
app.post('/charge', async (req, res) => {
  try {
    const charge = await omise.charges.create({
      amount: req.body.amount,
      currency: req.body.currency,
      card: req.body.token
    });
    res.json({ success: true, charge_id: charge.id });

  } catch (error) {
    // Log full error server-side
    console.error('Charge failed:', error);

    // Return safe message to client
    const safeMessage = {
      success: false,
      error: {
        code: error.code || 'unknown',
        message: getUserFriendlyMessage(error.code)
      }
    };

    res.status(error.statusCode || 500).json(safeMessage);
  }
});

Debugging Errors

1. Use Test Mode for Development

Always use test API keys during development:

# ✅ Test mode - safe for debugging
export OMISE_SECRET_KEY=skey_test_5xuy4w91xqz7d1w9u0t

# Test mode errors are identical to live mode
curl https://api.omise.co/charges \
  -X POST \
  -u $OMISE_SECRET_KEY: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "card=tokn_test_no1t4tnemucod0e51mo"

2. Check Request/Response in Dashboard

Go to Dashboard → Logs
View all API requests and responses
See exact error details
Review request parameters

3. Enable Debug Logging

# Ruby - Enable debug logging
require 'omise'

Omise.api_key = ENV['OMISE_SECRET_KEY']
Omise.debug = true  # Prints HTTP requests/responses

charge = Omise::Charge.create({
  amount: 100000,
  currency: 'thb',
  card: token
})

# Python - Enable debug logging
import omise
import logging

# Enable HTTP debugging
logging.basicConfig(level=logging.DEBUG)

omise.api_secret = os.environ['OMISE_SECRET_KEY']

// Node.js - Use request interception
const omise = require('omise')({
  secretKey: process.env.OMISE_SECRET_KEY
});

// Log all requests/responses
omise.interceptor = {
  request: (config) => {
    console.log('Request:', config);
    return config;
  },
  response: (response) => {
    console.log('Response:', response);
    return response;
  },
  responseError: (error) => {
    console.error('Error:', error);
    throw error;
  }
};

4. Test with Curl

# Verbose output shows full HTTP exchange
curl -v https://api.omise.co/charges \
  -X POST \
  -u skey_test_...: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "card=tokn_test_..."

# Shows:
# > POST /charges HTTP/1.1
# > Authorization: Basic ...
# > Content-Type: application/x-www-form-urlencoded
# < HTTP/1.1 200 OK
# < Content-Type: application/json

5. Common Debugging Steps

For Authentication Errors:

✅ Copy API key from Dashboard (don't type manually)
✅ Check for extra spaces or line breaks
✅ Verify test vs live key matches environment
✅ Ensure Authorization header format: Basic base64(key:)

For Payment Errors:

✅ Try with test card numbers first
✅ Verify card details are correct
✅ Check if card supports online payments
✅ Test with different cards to isolate issue

For Validation Errors:

✅ Read error message carefully
✅ Check API documentation for parameter requirements
✅ Verify data types (number vs string)
✅ Check minimum/maximum values

For Server Errors:

✅ Check status.omise.co
✅ Retry after a delay
✅ Contact support if persistent
✅ Save request/response for debugging

Error Handling Checklist

Before going live, ensure your error handling:

Testing Error Scenarios

Test Authentication Errors

# Invalid API key
curl https://api.omise.co/account \
  -u invalid_key:
# Returns 401 authentication_failure

# Wrong key type
curl https://api.omise.co/charges \
  -X POST \
  -u pkey_test_...: \
  -d "amount=100000"
# Returns 401 authentication_failure

Test Validation Errors

# Amount too small
curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_...: \
  -d "amount=100" \
  -d "currency=thb"
# Returns 400 bad_request

# Invalid currency
curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_...: \
  -d "amount=100000" \
  -d "currency=invalid"
# Returns 400 bad_request

Test Payment Errors

Use special test cards that trigger specific errors:

# Insufficient funds
curl https://vault.omise.co/tokens \
  -X POST \
  -u pkey_test_...: \
  -d "card[number]=4111111111111111" \
  -d "card[name]=Test User" \
  -d "card[expiration_month]=12" \
  -d "card[expiration_year]=2025" \
  -d "card[security_code]=123"
# Use token in charge - will decline with insufficient_fund

# Failed processing
curl https://vault.omise.co/tokens \
  -X POST \
  -u pkey_test_...: \
  -d "card[number]=4000000000000002" \
  -d "card[name]=Test User" \
  -d "card[expiration_month]=12" \
  -d "card[expiration_year]=2025" \
  -d "card[security_code]=123"
# Use token in charge - will decline with failed_processing

View all test cards →

FAQ

Should I retry failed payments automatically?

No, don't automatically retry payment failures (4xx errors). Repeatedly attempting declined cards can:

Trigger fraud alerts
Get cards blocked by issuers
Frustrate customers

Instead:

Show clear error message
Ask customer to verify payment details
Suggest alternative payment method
Let customer manually retry when ready

You can retry server errors (5xx) with exponential backoff.

How do I know if a charge failed?

Check the HTTP status code and charge status:

Success:

HTTP 200 OK
charge.status = "successful" (captured)
charge.status = "pending" (authorized, not captured yet)

Failure:

HTTP 402 Payment Required
Error response with code like payment_declined
charge.status = "failed" or "expired"

What's the difference between 4xx and 5xx errors?

4xx = Client Errors (your fault)

Your request was invalid
Fix the request and retry
Examples: bad parameters, declined payment, invalid auth

5xx = Server Errors (our fault)

Something went wrong on Omise's side
Request was valid, but couldn't be processed
Retry with backoff
Examples: service down, internal error

How long should I wait before retrying?

Use exponential backoff:

First retry: Wait 1 second
Second retry: Wait 2 seconds
Third retry: Wait 4 seconds
Fourth retry: Wait 8 seconds
Give up after 3-5 attempts

async function retryWithBackoff(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.statusCode < 500 || attempt === maxAttempts - 1) {
        throw error;
      }
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Can I get more details about payment failures?

Payment failure reasons are intentionally limited for security. Card issuers don't always provide specific decline reasons to prevent fraud.

What you get:

✅ High-level error code (insufficient_fund, invalid_card)
✅ Generic error message

What you don't get:

❌ Exact card balance
❌ Specific fraud flags
❌ Internal bank codes

This protects cardholders from attackers testing stolen cards.

Quick Reference

Error Response Structure

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#<error-code>",
  "code": "<error_code>",
  "message": "<human-readable message>"
}

Common Status Codes

Status	Meaning	Action
200	Success	Process response
400	Bad Request	Fix parameters
401	Unauthorized	Fix API key
402	Payment Failed	Show error, don't retry
404	Not Found	Verify resource ID
422	Invalid State	Check resource state
429	Rate Limited	Implement backoff
500	Server Error	Retry with backoff
503	Service Down	Retry later

Error Handling Pattern

Try API request
Catch error
Check HTTP status
Parse error code
Log error (server-side)
Show user message (safe)
Retry only if 5xx
Monitor error rates

Next: Learn about Pagination to handle large result sets efficiently.

Overview​

Error Response Format​

Error Object Fields​

HTTP Status Codes​

2xx Success​

200 OK​

201 Created​

4xx Client Errors​

400 Bad Request​

401 Unauthorized​

402 Payment Required​

404 Not Found​

422 Unprocessable Entity​

429 Too Many Requests​

5xx Server Errors​

500 Internal Server Error​

503 Service Unavailable​

Complete Error Code Reference​

400 Bad Request​

401 Unauthorized​

402 Payment Required​

403 Forbidden​

404 Not Found​

422 Unprocessable Entity​

429 Too Many Requests​

500 Internal Server Error​

503 Service Unavailable​

Error Codes by Category​

Authentication Errors​

Request Errors​

Payment Errors​

Operation Errors​

Transfer/Recipient Errors​

Dispute Errors​

System Errors​

Error Handling Best Practices​

1. Always Check HTTP Status First​

2. Parse Error Details​

3. Implement Retry Logic for Server Errors​

4. Validate Before Sending Requests​

5. Show User-Friendly Messages​

6. Log Errors for Debugging​

7. Don't Expose Sensitive Error Details​

Debugging Errors​

1. Use Test Mode for Development​

2. Check Request/Response in Dashboard​

3. Enable Debug Logging​

4. Test with Curl​

5. Common Debugging Steps​

Error Handling Checklist​

Testing Error Scenarios​

Test Authentication Errors​

Test Validation Errors​

Test Payment Errors​

FAQ​

Quick Reference​

Error Response Structure​

Common Status Codes​

Error Handling Pattern​

Related Resources​

Overview

Error Response Format

Error Object Fields

HTTP Status Codes

2xx Success

200 OK

201 Created

4xx Client Errors

400 Bad Request

401 Unauthorized

402 Payment Required

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

5xx Server Errors

500 Internal Server Error

503 Service Unavailable

Complete Error Code Reference

400 Bad Request

401 Unauthorized

402 Payment Required

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

Error Codes by Category

Authentication Errors

Request Errors

Payment Errors

Operation Errors

Transfer/Recipient Errors

Dispute Errors

System Errors

Error Handling Best Practices

1. Always Check HTTP Status First

2. Parse Error Details

3. Implement Retry Logic for Server Errors

4. Validate Before Sending Requests

5. Show User-Friendly Messages

6. Log Errors for Debugging

7. Don't Expose Sensitive Error Details

Debugging Errors

1. Use Test Mode for Development

2. Check Request/Response in Dashboard

3. Enable Debug Logging

4. Test with Curl

5. Common Debugging Steps

Error Handling Checklist

Testing Error Scenarios

Test Authentication Errors

Test Validation Errors

Test Payment Errors

FAQ

Quick Reference

Error Response Structure

Common Status Codes

Error Handling Pattern

Related Resources