{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "field": "X-Merchant-API-Key",
      "provided": "sk_test_***"
    },
    "request_id": "req_1234567890",
    "documentation": "https://docs.moneybag.com.bd/errors/INVALID_API_KEY"
  }
}

# Correct format
curl -H "X-Merchant-API-Key: sk_live_abcd1234..."

# Common mistakes
curl -H "API-Key: sk_live_abcd1234..."  # Wrong header name
curl -H "Authorization: Bearer sk_live_abcd1234..."  # Wrong format

const headers = {
  'X-Merchant-API-Key': process.env.MONEYBAG_API_KEY,
  'Content-Type': 'application/json'
};

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation",
    "details": {
      "amount": ["Amount must be greater than 10"],
      "email": ["Invalid email format"],
      "phone": ["Phone number must be 11 digits"]
    }
  }
}

// Implement session refresh
if (error.code === 'PAYMENT_TIMEOUT') {
    const newSession = await createPaymentSession(orderDetails);
    redirectToPayment(newSession.payment_url);
}

const order_id = `ORD_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;

// Check refundable amount first
const transaction = await getTransaction(transactionId);
const refundableAmount = transaction.amount - transaction.refunded_amount;

if (refundAmount > refundableAmount) {
    throw new Error(`Maximum refundable: ${refundableAmount}`);
}

// Use raw payload for verification
$payload = file_get_contents('php://input');
// Don't use $_POST or json_decode before verification

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 3600

async function apiCallWithRetry(fn, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            return await fn();
        } catch (error) {
            if (error.status === 429) {
                const retryAfter = error.headers['retry-after'] || Math.pow(2, i);
                await sleep(retryAfter * 1000);
            } else {
                throw error;
            }
        }
    }
}

// Production requires HTTPS
const config = {
    success_url: 'https://yoursite.com/success',  // ✓ HTTPS
    cancel_url: 'http://yoursite.com/cancel',     // ✗ HTTP not allowed
    fail_url: 'https://localhost/fail'            // ✗ Localhost not allowed
};

const signature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "request_id": "req_abc123",
    "support": "Please contact support with request_id"
  }
}

try {
    const response = await makeApiCall();
    return response.data;
} catch (error) {
    if (error.response) {
        // API returned error
        switch (error.response.status) {
            case 400:
                handleValidationError(error.response.data);
                break;
            case 401:
                refreshApiKey();
                break;
            case 429:
                await waitAndRetry(error);
                break;
            case 500:
                logErrorAndRetry(error);
                break;
            default:
                handleGenericError(error);
        }
    } else if (error.request) {
        // Network error
        handleNetworkError(error);
    } else {
        // Client error
        handleClientError(error);
    }
}

const userMessages = {
    'INSUFFICIENT_FUNDS': 'Your payment could not be processed due to insufficient funds.',
    'CARD_DECLINED': 'Your card was declined. Please try a different payment method.',
    'PAYMENT_TIMEOUT': 'Your payment session has expired. Please try again.',
    'RATE_LIMIT_EXCEEDED': 'Too many requests. Please wait a moment and try again.'
};

function getUserMessage(errorCode) {
    return userMessages[errorCode] || 'An error occurred. Please try again.';
}

function logError(error) {
    console.error({
        timestamp: new Date().toISOString(),
        request_id: error.request_id,
        error_code: error.code,
        message: error.message,
        details: error.details,
        stack: error.stack
    });
}

# Trigger webhook failure
curl -X POST https://sandbox.api.moneybag.com.bd/api/v2/webhooks/test \
  -H "X-Merchant-API-Key: YOUR_KEY" \
  -d '{
    "event": "webhook.failed",
    "url": "https://yoursite.com/webhook"
  }'