Error Responses

All errors returned by the API follow a consistent JSON format:

{
  "error": {
    "code": <integer>,
    "message": <string>,
    "details": <list>
  }
}

400 Bad Request

• Invalid input → request body fails validation
• Malformed JSON → body is not valid JSON
• Missing parameter → required field or query parameter not provided

Example:

{
  "error": {
    "code": 2002,
    "message": "Missing parameter: 'transaction_id'",
    "details": []
  }
}

401 Unauthorized

• Missing API key
• Missing signature
• Invalid signature

Example:

{
  "error": {
    "code": 1003,
    "message": "Invalid signature",
    "details": []
  }
}

403 Forbidden

• Permission denied → client does not have rights to access resource

Example:

{
  "error": {
    "code": 2004,
    "message": "Permission denied",
    "details": []
  }
}

404 Not Found

• Transaction not found → ID or reference does not exist
• Gateway not found → provided gateway is not available

Example:

{
  "error": {
    "code": 1006,
    "message": "Transaction not found",
    "details": []
  }
}

422 Unprocessable Entity

• Invalid parameter value → type mismatch or unsupported format

Example:

{
  "error": {
    "code": 2005,
    "message": "Invalid parameter value",
    "details": [
      {"field": "amount", "error": "Must be a positive number"}
    ]
  }
}

---

500 Internal Server Error

• Unexpected runtime error
• Invalid response from service