Skip to main content

​
Error Handling

SwiftPay uses conventional HTTP response codes to indicate the success or failure of an API request.

​
HTTP Status Codes

CodeDescription
200Success - The request completed successfully
201Created - A new resource was created
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Valid key but insufficient permissions
404Not Found - The requested resource doesn’t exist
409Conflict - The request conflicts with current state
422Validation Error - The request body failed validation
429Rate Limited - Too many requests
500Server Error - Something went wrong on our end

​
Error Response Format

All error responses follow a consistent format: 
{
   "success": false,
   "error": {
      "type": "validation_error",
      "message": "Request validation failed",
      "requestId": "req_abc123xyz",
      "fields": {
         "email": "Invalid email format",
         "amount": "Amount must be greater than 0"
      }
   }
}

​
Error Object Properties

​
type
string
required
The type of error. One of: - unauthenticated - Invalid or missing API key - unauthorized - Insufficient permissions - validation_error - Invalid request parameters - not_found - Resource not found - conflict - Resource state conflict - rate_limit_exceeded - Too many requests - internal_server_error - Internal server error - external_service_error - External service error - database_error - Database error
​
message
string
required
A human-readable description of the error.
​
requestId
string
required
A unique identifier for this request. Include this when contacting support.
​
fields
object
For validation errors, an object containing field-specific error messages.

​
Error Types

​
Authentication Error

Returned when the API key is missing or invalid. 
{
   "success": false,
   "error": {
      "type": "unauthenticated",
      "message": "Invalid API key provided",
      "requestId": "req_abc123"
   }
}

​
Validation Error

Returned when request parameters fail validation. 
{
   "success": false,
   "error": {
      "type": "validation_error",
      "message": "Request validation failed",
      "requestId": "req_abc123",
      "fields": {
         "items": "At least one item is required",
         "customer.email": "Invalid email format"
      }
   }
}

​
Not Found Error

Returned when the requested resource doesn’t exist. 
{
   "success": false,
   "error": {
      "type": "not_found",
      "message": "Checkout session not found",
      "requestId": "req_abc123"
   }
}

​
Conflict Error

Returned when the request conflicts with the current state. 
{
   "success": false,
   "error": {
      "type": "conflict",
      "message": "This checkout session has already been paid",
      "requestId": "req_abc123"
   }
}

​
Handling Errors

async function createCheckoutSession(data) {
  try {
    const response = await fetch('https://api.swiftpay.cx/api/checkout/sessions', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer mp_live_your_api_key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
    
    const result = await response.json();
    
    if (!result.success) {
      // Handle specific error types
      switch (result.error.type) {
        case 'validation_error':
          console.error('Validation failed:', result.error.fields);
          break;
        case 'unauthenticated':
          console.error('Check your API key');
          break;
        default:
          console.error('Error:', result.error.message);
      }
      return null;
    }
    
    return result.data;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}

​
Best Practices

Log Request IDs

Always log the requestId from error responses. This helps our support team debug issues quickly.

Retry on 5xx

Server errors (5xx) are usually temporary. Implement exponential backoff and retry logic.

Validate Locally

Validate request data before sending to reduce validation errors.

Handle Edge Cases

Always handle error responses gracefully to provide a good user experience.