Error Handling

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created successfully
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`404`	Not Found - Resource doesn't exist
`409`	Conflict - Duplicate request (idempotency)
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Response Format

{
  "status": false,
  "message": "Description of the error",
  "data": null
}

Common Errors

Authentication Errors

{
  "status": false,
  "message": "Invalid API key"
}

Validation Errors

{
  "status": false,
  "message": "Validation failed for 2 of 5 transfers",
  "summary": {
    "total": 5,
    "successful": 3,
    "failed": 2
  },
  "errors": [
    {
      "index": 0,
      "reference": "txn_abc123",
      "errors": [
        {
          "code": "INVALID_AMOUNT",
          "field": "amount",
          "message": "Amount must be greater than 0",
          "value": -500
        }
      ]
    },
    {
      "index": 3,
      "reference": "txn_xyz789",
      "errors": [
        {
          "code": "INVALID_ACCOUNT",
          "field": "account_number",
          "message": "Account number must be 10 digits",
          "value": "12345"
        }
      ]
    }
  ]
}

Insufficient Balance

{
  "status": false,
  "message": "Insufficient balance in account 12345. Required: 10000, Available: 5000"
}

Idempotency Conflict

{
  "status": false,
  "message": "A request with this idempotency key is already in progress"
}

Retry Policy & Best Practices

Idempotency