Errors & retries - Broco Developers

When Broco cannot process a request, it returns an HTTP error status and an error object.

Response

{
  "error": {
    "code": "connection_not_authorized",
    "message": "The connection conn_mrc_4f7Kp2 is not authorized for this operation.",
    "request_id": "req_6Gm1Zt8e"
  }
}

Keep the request_id. It helps Broco find the request when you contact support.

Error codes

HTTP status	`code`	Meaning	What to do
`400`	`invalid_request`	A field is missing or malformed	Fix the request
`400`	`invalid_amount`	The amount is not a positive integer in the currency’s minor unit	Send minor units, such as `5000000` for 50 000 DZD. See Currencies & amounts.
`400`	`unsupported_currency`	The currency is not in the specification	Use `DZD`, `MAD`, `TND` or `XOF`
`400`	`currency_mismatch`	The currency cannot be used with the Broco accounts involved	Use a currency accepted by those accounts
`401`	`authentication_failed`	The integration secret is missing or invalid	Check the `Authorization` header
`403`	`connection_not_authorized`	The connection is unknown, revoked or not allowed for this operation	Ask the account owner to connect again
`403`	`beneficiary_not_authorized`	The beneficiary is not authorized for this business	Ask the business to add the supplier in Broco
`404`	`resource_not_found`	The object does not exist	Check the identifier
`409`	`idempotency_key_reused`	The key was already used with different parameters	Use a new key for a new request
`409`	`invalid_status`	The operation is not allowed in the current status	Retrieve the object to read its status
`429`	`rate_limited`	Too many requests	Retry later with the same key
`500`	`internal_error`	Broco could not confirm the result. The operation may or may not have been completed.	Retry with the same key. Never send it with a new key.

Errors and outcomes

Some situations are normal outcomes reported in the object’s status, not request errors.

Situation	Where you see it
Customer balance too low	Payment `declined`, `decline_reason: insufficient_balance`
Customer refuses	Payment `declined`, `decline_reason: customer_declined`
Cash not paid in time	Cash payment `expired`
Approver rejects	Supplier payment `rejected`
Business balance too low	Supplier payment `declined`, `decline_reason: insufficient_balance`
Deposit not made by the deadline	Collection with `deposit.overdue: true`
Amount deposited differs	Collection `deposit_under_review`

Retry rules

Case	Action
Timeout or network error on a creation	Retry the same request with the same `Idempotency-Key`
`429` or `500`	Retry later with the same key
`4xx` other than `429`	Fix the request. Do not retry unchanged.
A previous attempt reached a final failure status	Create a new attempt with a new key

Never create a new object with a new key just because a response did not arrive or returned 500. The first request may have succeeded. Retry with the same key or retrieve the object first.