> ## Documentation Index
> Fetch the complete documentation index at: https://docs.broco.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & retries

> Error responses, what they mean, and how to retry without creating duplicates.

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

```json Response theme={null}
{
  "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](/developer/currencies-and-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.