Error Codes

Complete reference for all error codes, their meanings, and how to handle them in your application.

Error Response Format

Standard Error Response
All errors follow this format
{
  "error": {
    "code": "invalid_card",
    "message": "The card number provided is invalid",
    "type": "card_error",
    "details": {
      "field": "card_number",
      "reason": "invalid_format"
    }
  }
}

Error Codes Reference

invalid_request
400

The request is malformed or missing required parameters

Solution:

Check your request body and ensure all required fields are present and correctly formatted

authentication_failed
401

The API key is invalid or missing

Solution:

Verify your Authorization header includes a valid Bearer token with your Secret Key

forbidden
403

The API key doesn't have permission for this action

Solution:

Ensure you're using the correct key type and it has the required permissions

not_found
404

The requested resource was not found

Solution:

Verify the resource ID exists and belongs to your account

conflict
409

A conflict occurred, often due to duplicate idempotency keys

Solution:

Use a unique idempotency key for each request

invalid_card
422

The card data is invalid or the card was declined

Solution:

Check the card number, expiry, and CVV. Verify the card is active and has sufficient funds

insufficient_funds
402

The card doesn't have sufficient funds for this transaction

Solution:

Ask the customer to use a different payment method or card

rate_limit_exceeded
429

Too many requests in a short period

Solution:

Implement exponential backoff and reduce request frequency

server_error
500

An internal server error occurred

Solution:

Retry the request after a short delay. If the issue persists, contact support

Error Handling Best Practices

Recommended Approach
  • •
    Check error codes: Use the error code to determine the appropriate action rather than parsing error messages
  • •
    User-friendly messages: Map error codes to user-friendly messages instead of showing technical error details
  • •
    Retry logic: Implement retry logic for transient errors (5xx) with exponential backoff
  • •
    Log errors: Log all errors with context for debugging, but don't expose sensitive details to users
  • •
    Handle gracefully: Always provide a fallback option when payments fail (e.g., "Please try again" or "Use a different payment method")

HTTP Status Codes

Client Errors (4xx)
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 409 - Conflict
  • 422 - Unprocessable Entity
  • 429 - Too Many Requests
Server Errors (5xx)
  • 500 - Internal Server Error
  • 502 - Bad Gateway
  • 503 - Service Unavailable
  • 504 - Gateway Timeout