Error Handling

Common API Errors

Our VoP API returns clear, actionable error messages to help you handle issues quickly:

✅ MATCH - Success

{
  "result": "MATCH",
  "confidence": "HIGH",
  "message": "Verification successful"
}

❌ NO_MATCH - Failed Verification

{
  "result": "NO_MATCH",
  "confidence": "HIGH",
  "message": "Name does not match account holder",
  "action": "Block payment - potential fraud"
}

⚠️ PARTIAL_MATCH - Needs Review

{
  "result": "PARTIAL_MATCH",
  "confidence": "MEDIUM",
  "message": "Close match found - minor spelling difference",
  "action": "Additional verification recommended"
}

🚫 ERROR - System Issue

{
  "error": "TIMEOUT",
  "message": "Service temporarily unavailable",
  "action": "Retry in 30 seconds"
}

How to Handle Errors

1️⃣ Check Response Status

if (response.result === 'MATCH') {
  // Proceed with payment
  processPayment(paymentData);
} else if (response.result === 'NO_MATCH') {
  // Block payment - potential fraud
  blockPayment('Fraud risk detected');
} else if (response.result === 'PARTIAL_MATCH') {
  // Request additional verification
  requestManualReview(paymentData);
}

2️⃣ Handle System Errors

try {
  const response = await vopApi.verify(iban, name);
  return response;
} catch (error) {
  if (error.type === 'TIMEOUT') {
    // Retry after delay
    await delay(30000);
    return vopApi.verify(iban, name);
  }
  // Log error and use fallback
  logError(error);
  return { result: 'ERROR', message: 'Service unavailable' };
}

## Best Practices

### ✅ **Do This**
- **Always check response status** before processing payments
- **Implement retry logic** for timeout errors
- **Log all errors** for debugging and monitoring
- **Use fallback procedures** when service is unavailable

### ❌ **Avoid This**
- Don't ignore PARTIAL_MATCH results
- Don't retry immediately on errors
- Don't proceed with payments on NO_MATCH
- Don't expose error details to end users