Errors

🧾 Error Response Structure

All error responses follow a consistent format:

🔢 HTTP Status Codes

🚨 Common Error Types

1. Authentication Errors

• Invalid or expired SessionToken
• Missing Authorizationheader

👉 Fix: Regenerate token via /auth

2. Validation Errors

• Missing required fields
• Incorrect field formats (email, amount, etc.)
• Invalid enum values

👉 Fix: Validate request body against API specs

3. Business Logic Errors

• Invalid Beneficiary / Payment Instrument ID
• Insufficient balance
• Compliance rejection

👉 Fix: Verify data and transaction eligibility

4. File Upload Errors

• File size exceeds limit (5 MB)
• Invalid file type or name
• Incorrect customField mapping

👉 Fix: Follow file constraints and mapping rules

⚠️ Error Response Format

All APIs in the system return errors in a consistent structure, making it easier to debug and handle failures programmatically.

🧾 Error Structure

{
  "ResponseCode": 400,
  "ResponseMessage": "BadRequest",
  "RequestID": "unique-request-id",
  "ResponseErrors": [
    "Detailed error message"
  ]
}

Fields:

• ResponseCode → HTTP status code
• ResponseMessage → High-level error type
• RequestID → Unique identifier for tracing the request
• ResponseErrors → List of detailed error messages

🧩 Types of Errors In Response

1. Validation Errors

Occurs when request input is missing or invalid.

Examples:

{
  "ResponseCode": 400,
  "ResponseMessage": "BadRequest",
  "RequestID": "3af1ad70-3e57-11f1-af90-b99d00c047b3",
  "ResponseErrors": [
    "body[Address]: Mandatory Fields are Missing."
  ]
}

{
  "ResponseCode": 400,
  "ResponseMessage": "BadRequest",
  "RequestID": "5e922930-3e57-11f1-af90-b99d00c047b3",
  "ResponseErrors": [
    "body[Address]: Invalid Data."
  ]
}

👉 How to handle:

• Ensure all required fields are provided
• Validate data formats before sending requests

2. Business Logic Errors

Occurs when the request is valid but violates system rules.

Example:

{
  "ResponseCode": 400,
  "ResponseMessage": "BadRequest",
  "RequestID": "7f8e38e0-3e57-11f1-af90-b99d00c047b3",
  "ResponseErrors": [
    "The account you are trying to add already exists"
  ]
}

👉 How to handle:

• Check existing data before creating new records
• Avoid duplicate or conflicting operations

🧠 Best Practices

• Always log the RequestID for debugging and support
• Parse ResponseErrors to display meaningful messages to users
• Do not retry requests without fixing the underlying issue

📌 Summary

GET 400 Error → Check ResponseErrors → Fix Input / Data → Retry

This structure ensures clear, traceable, and actionable error handling across all APIs.

🔁 Handling Token Expiry

• If API returns 401 Unauthorized, regenerate SessionToken

• If x-refresh-token is returned in headers:

  • Replace existing token

  • Continue without re-authentication

🧠 Best Practices

• Always log ResponseCode and ResponseMessage
• Use Webhooks to track transaction failures
• Implement retry logic only for safe operations
• Avoid retrying failed payments without validation