Errors ​

When an API request cannot be completed successfully, the response body describes the failure and the HTTP status code tells you how to handle it.

Every error response includes a correlationId. Send this value to Bui support when you need help with a failed request. If the request contains request-id, x-request-id, or x-idempotence-key, that value is reused as the correlationId; otherwise the API generates one.

Business errors can also include a causationId, which identifies the exact internal error occurrence.

Error response ​

{
  "error": "Conflict",
  "statusCode": 409,
  "correlationId": "d84caf0f-0941-4998-8376-68c7c9ab7913",
  "causationId": "de0c0e48-b9bb-46d6-9b6e-341b7b687473",
  "message": "payment can not processed, recipient not match with selected service PAYIN_ORANGE_CI"
}

HTTP status codes ​

Authentication errors ​

Requests protected with Bearer authentication return 401 when the Authorization header is missing, not using Bearer, using an invalid token prefix, or when the token does not match an active company.

{
  "statusCode": 401,
  "message": "unauthenticated",
  "error": "Unauthorized",
  "correlationId": "dd2d2d17-4ea3-4e45-bd3e-994b949ccb5c"
}

Validation errors ​

Validation errors return 422 with subErrors. These errors are usually caused by missing required fields, invalid service identifiers, invalid URLs, invalid phone numbers, non-positive amounts, or invalid enum values such as paymentMethod or transferMethod.

{
  "statusCode": 422,
  "message": "Validation error",
  "error": "Unprocessable Entity",
  "subErrors": [
    "mobileMoney.amount must be a positive number",
    "mobileMoney.recipient must be a valid phone number"
  ],
  "correlationId": "7a00d969-c5dd-4d80-a445-5939ed13c03d"
}

Business error catalogue ​

The table below lists the business error codes currently mapped by the public API error handler. Some API responses expose only the HTTP statusCode, error, message, correlationId, and causationId; keep the correlationId and the request payload in your logs so support can match the response to the internal code.

Integration guidance ​

Use the HTTP status code first when deciding how to react: