Errors and Retries

This guide explains how to handle errors and implement retry logic when integrating with Fatoorah Pay API.

Error Response Format

All API errors follow a standardized format:

{
  "success": false,
  "error": {
    "code": "AK-401",
    "message": "Invalid API key provided.",
    "timestamp": "2025-12-04T10:00:00Z",
    "path": "/api/v1/payment-links"
  }
}

Error Fields

code - Unique error code for programmatic handling
message - Human-readable error message
timestamp - When the error occurred (ISO 8601)
path - API endpoint that caused the error

HTTP Status Codes

Status Code	Meaning	Action
200	Success	Process response normally
400	Bad Request	Check request parameters
401	Unauthorized	Verify API key
403	Forbidden	Check permissions or environment mismatch
404	Not Found	Verify resource ID
429	Too Many Requests	Implement rate limiting
500	Internal Server Error	Retry with backoff

Common Error Codes

Authentication Errors

AK-401: Invalid API Key

{
  "error": {
    "code": "AK-401",
    "message": "Invalid API key provided."
  }
}

Causes:

API key is incorrect
API key has been revoked
API key has expired

Solutions:

Verify API key is correct
Check key hasn't been revoked in dashboard
Generate a new API key if needed

AK-403: API Key Environment Mismatch

{
  "error": {
    "code": "AK-403",
    "message": "API key environment does not match requested operation mode. Test keys cannot be used for live transactions and vice versa."
  }
}

Causes:

Using test key (sk_test_xxx) with isLive: true
Using live key (sk_live_xxx) with isLive: false

Solutions:

Use test key with isLive: false
Use live key with isLive: true

Validation Errors

D-400: Validation Error

{
  "error": {
    "code": "D-400",
    "message": "Validation failed for the request."
  }
}

Causes:

Missing required fields
Invalid field format
Field values out of range

Solutions:

Check request body against API documentation
Verify all required fields are present
Validate field formats (email, phone, etc.)

D-400: Invalid Transaction Data

{
  "error": {
    "code": "D-400",
    "message": "Invalid transaction data provided."
  }
}

Causes:

Amount is zero or negative
Currency code invalid
Item amounts don't match total

Solutions:

Ensure amount > 0
Use valid currency code (e.g., "SAR")
Verify item amounts sum to total amount

Not Found Errors

TRANSACTION_NOT_FOUND

{
  "error": {
    "code": "T-404",
    "message": "Transaction not found."
  }
}

Solutions:

Verify transaction ID is correct
Check transaction belongs to your account
Use display ID format: FT-XXXXXXXXXX

Rate Limiting

AK-429: API Key Limit Exceeded

{
  "error": {
    "code": "AK-429",
    "message": "API key limit exceeded for this account."
  }
}

Causes:

Too many API keys created (max 100 per account)

Solutions:

Revoke unused API keys
Contact support if you need more keys

Rate Limit Headers

When rate limited, response includes:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1634567890

Retry Logic

When to Retry

Retry requests for:

✅ 5xx errors - Server errors (temporary)
✅ 429 errors - Rate limiting (temporary)
✅ Network errors - Connection failures
✅ Timeouts - Request timeouts

Don't retry:

❌ 4xx errors - Client errors (fix request)
❌ 401 errors - Authentication issues (fix API key)

Exponential Backoff

Implement exponential backoff for retries:

async function retryWithBackoff(fn, maxRetries = 3) {
  let delay = 1000; // Start with 1 second
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      
      // Don't retry client errors
      if (error.status >= 400 && error.status < 500) {
        throw error;
      }
      
      // Wait before retry
      await sleep(delay);
      delay *= 2; // Exponential backoff
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Retry Example

async function createPaymentLink(data) {
  return retryWithBackoff(async () => {
    const response = await fetch('https://pay.fatoorah.ai/api/v1/payment-links', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': process.env.FATOORAH_API_KEY
      },
      body: JSON.stringify(data)
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.error.code} - ${error.error.message}`);
    }
    
    return response.json();
  });
}

Error Handling Best Practices

1. Always Check Response Status

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  handleError(error);
  return;
}

const data = await response.json();

2. Handle Specific Error Codes

function handleError(error) {
  switch (error.error.code) {
    case 'AK-401':
      // Invalid API key - don't retry
      console.error('Invalid API key');
      break;
      
    case 'AK-403':
      // Environment mismatch - don't retry
      console.error('API key environment mismatch');
      break;
      
    case 'D-400':
      // Validation error - don't retry
      console.error('Validation error:', error.error.message);
      break;
      
    case 'G-500':
      // Server error - retry
      console.error('Server error, will retry');
      break;
      
    default:
      console.error('Unknown error:', error);
  }
}

3. Log Errors for Debugging

function logError(error, context) {
  console.error('API Error:', {
    code: error.error?.code,
    message: error.error?.message,
    path: error.error?.path,
    timestamp: error.error?.timestamp,
    context: context
  });
  
  // Send to error tracking service
  errorTracker.captureException(error, { context });
}

4. Provide User-Friendly Messages

function getUserFriendlyMessage(errorCode) {
  const messages = {
    'AK-401': 'Authentication failed. Please check your API key.',
    'AK-403': 'API key environment mismatch. Use test key for test mode.',
    'D-400': 'Invalid request. Please check your input.',
    'T-404': 'Transaction not found.',
    'G-500': 'Server error. Please try again later.'
  };
  
  return messages[errorCode] || 'An error occurred. Please try again.';
}

Common Error Scenarios

Scenario 1: Invalid API Key

// Request
const response = await fetch(url, {
  headers: { 'X-API-KEY': 'invalid_key' }
});

// Response: 401
{
  "error": {
    "code": "AK-401",
    "message": "Invalid API key provided."
  }
}

// Solution
// Verify API key is correct
// Check key hasn't been revoked
// Generate new key if needed

Scenario 2: Environment Mismatch

// Request with test key but isLive: true
{
  "isLive": true,  // ❌ Wrong!
  "data": { ... }
}

// Response: 403
{
  "error": {
    "code": "AK-403",
    "message": "API key environment does not match..."
  }
}

// Solution
// Use test key with isLive: false
// Or use live key with isLive: true

Scenario 3: Validation Error

// Request with missing required field
{
  "data": {
    "amount_cents": 10000
    // Missing: full_name, phone_number, description
  }
}

// Response: 400
{
  "error": {
    "code": "D-400",
    "message": "Validation failed for the request."
  }
}

// Solution
// Include all required fields
// Verify field formats

Scenario 4: Rate Limiting

// Too many requests
// Response: 429
{
  "error": {
    "code": "AK-429",
    "message": "Rate limit exceeded."
  }
}

// Response headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1634567890

// Solution
// Wait until X-RateLimit-Reset
// Implement exponential backoff
// Reduce request frequency

Rate Limiting

Limits

Test keys: 100 requests/minute
Live keys: 1000 requests/minute

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1634567890

Handling Rate Limits

async function makeRequest(url, options) {
  const response = await fetch(url, options);
  
  // Check rate limit
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
  
  if (response.status === 429) {
    // Calculate wait time
    const waitTime = (resetTime * 1000) - Date.now();
    await sleep(waitTime);
    
    // Retry request
    return makeRequest(url, options);
  }
  
  return response;
}

Best Practices

Always handle errors - Don't ignore error responses
Check status codes - Verify response.ok before processing
Implement retries - Use exponential backoff for server errors
Log errors - Keep logs for debugging
Don't retry client errors - Fix the request instead
Respect rate limits - Monitor rate limit headers
Provide user feedback - Show friendly error messages

Related Guides

Authentication - API key authentication
Test Credentials - Test environment
Webhook Setup - Webhook error handling