BRE-B disbursement errors

Below are the specific error codes that may occur when interacting with BRE-B disbursement endpoints (preview and payment creation).

Error format

Error responses follow this structure:

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_033",
  "message": "El valor de la llave BRE-B no tiene un formato válido.",
  "type": "Business"
}

Field	Description
status	HTTP status code
meta.trace_id	Unique request identifier for traceability
code	Internal error code
message	Human-readable error description
type	Classification: Business (business rule) or Technical (technical error)

Preview errors

Errors that occur when resolving a BRE-B key with the GET /v2/breb/keys/resolve/{keyValue} endpoint.

Code	HTTP	Type	Message	Recommended action
EXC_033	400	Business	El valor de la llave BRE-B no tiene un formato válido.	Verify the key value matches the expected format for its type (see formats table below)
EXC_034	404	Business	La llave BRE-B no se encuentra activa o no está registrada.	Confirm with the beneficiary that the key is registered and active at their financial institution
EXC_035	400	Business	La llave BRE-B existe pero no está activa.	The key is registered but was deactivated. The beneficiary must reactivate it at their financial institution
EXC_036	503	Technical	El servicio de resolución BRE-B no está disponible.	Retry after a few seconds. If it persists, contact support
EXC_037	503	Technical	Tiempo de espera agotado al resolver la llave BRE-B.	Retry after a few seconds. If it persists, contact support

Disbursement creation errors

Errors that occur when creating a batch with the POST /v2/payouts endpoint.

Code	HTTP	Type	Message	Recommended action
EXC_001	500	Technical	Se presentó error interno procesando la solicitud.	Retry the request. If it persists, contact support with the trace_id
EXC_008	400	Business	Saldo insuficiente para procesar el lote.	Check available balance in the source account with GET /accounts
EXC_017	400	Business	Se ha alcanzado el límite diario.	Wait until the next day or contact support to increase the limit
EXC_018	400	Business	Se ha alcanzado el límite de transacciones del plan.	Contact support to upgrade the plan
EXC_019	400	Business	No se puede realizar el pago con la cuenta elegida.	Verify the source account is active and enabled for disbursements
EXC_032	409	Business	La llave de idempotencia ya fue procesada.	Use a new idempotency-key. Each key expires in 24 hours

Authentication and authorization errors

Apply to all BRE-B endpoints.

Code	HTTP	Message	Recommended action
401	401	Unauthorized	Verify the x-api-key is correct and is being sent in the headers
403	403	Payer not found	Verify the user-principal-id corresponds to a registered payer
403	403	Customer is employed and not allowed	The user does not have disbursement permissions. Contact the administrator
403	403	Payer not have active product	The payer does not have the Third-Party Payments product active. Activate it from the dashboard

Field validation errors

When fields with incorrect format or missing fields are sent, a 400 error is returned with an array of messages:

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "400",
  "message": [
    "reference must be a string",
    "reference should not be empty"
  ],
  "data": {
    "message": [
      "reference must be a string",
      "reference should not be empty"
    ],
    "error": "Bad Request",
    "statusCode": 400
  }
}

Idempotency-key validations

Message	Cause
The key can only contain letters, numbers, and hyphens	The idempotency-key contains disallowed special characters

Body validations

Message	Cause
reference must be a string	reference field missing or with incorrect type
reference should not be empty	reference field empty
accountId must be a string	accountId field missing
paymentType must be one of: PAYROLL, PROVIDERS, OTHER	Invalid paymentType value
transactions must contain at least 1 element	Empty transactions array
amount must be a positive number	Negative or zero amount
email must be an email	Invalid email format
name should not be empty	Empty beneficiary name

BRE-B key formats

Quick reference to validate the format before sending the request:

Type	Expected format	Valid example	Pattern
ALPHANUMERIC	@ + 5 to 20 alphanumeric characters	@JUANPEREZ	^@[a-zA-Z0-9]{5,20}$
MAIL	Valid email	juan@email.com	RFC 5322
PHONE	10 digits, starts with 3	3001234567	^3[0-9]{9}$
IDENTIFICATION	1 to 18 alphanumeric characters	1234567890	^[a-zA-Z0-9]{1,18}$
ESTABLISHMENT_CODE	8 digits	12345678	^[0-9]{8}$

Best practices for error handling

• Always capture the trace_id: When reporting an error to support, include the response's trace_id to facilitate traceability.
• Retries for technical errors: Errors with type: "Technical" (EXC_001, EXC_036, EXC_037) may be transient. Implement retries with exponential backoff.
• Do not retry business errors: Errors with type: "Business" (EXC_008, EXC_033, EXC_034) require request correction before retrying.
• Validate locally before sending: Validate the BRE-B key format against the patterns in the table before making the API request.