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

Common Error Codes

Authentication Errors

Code	HTTP Status	Description	Solution
`authentication_failure`	401	Invalid or missing API key	Verify API key is correct
`forbidden`	403	Key lacks required permissions	Use secret key for this operation

Request Errors

Code	HTTP Status	Description	Solution
`bad_request`	400	Invalid request parameters	Check required parameters and formats
`invalid_charge`	422	Charge state doesn't allow operation	Verify charge status first
`invalid_customer`	422	Customer operation not allowed	Check customer state
`not_found`	404	Resource doesn't exist	Verify resource ID

Payment Errors

Code	HTTP Status	Description	Solution
`payment_declined`	402	Payment was declined	Ask customer to use different card
`insufficient_fund`	402	Not enough balance	Request different payment method
`invalid_card`	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
`payment_cancelled`	402	Customer cancelled payment	Customer action
`payment_expired`	402	Payment window expired	Create new charge

System Errors

Code	HTTP Status	Description	Solution
`internal_server_error`	500	Server-side error	Retry with backoff
`service_unavailable`	503	Service temporarily down	Wait and retry
`rate_limit_exceeded`	429	Too many requests	Implement rate limiting

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​

Common Error Codes​

Authentication Errors​

Request Errors​

Payment 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

Common Error Codes

Authentication Errors

Request Errors

Payment 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