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

# Limits

> The limits on your requests, orders and allocations, and what happens when you reach one.

We set four limits for each partner. Until we agree different values with you, the defaults below apply. Ask us to change them.

| Limit                        | Default                  | What it counts                                                                                                                                     |
| ---------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Requests per second          | 20, with bursts up to 40 | Every request made with any of your keys, counted together.                                                                                        |
| Requests in progress at once | 5                        | `POST /v1/orders`, `POST /v1/orders/estimate`, `DELETE /v1/orders/{id}`, `POST /v1/applications` and `POST /v1/allocations`, across all your keys. |
| Order value per day          | ₦10,000,000              | The value of the orders you place in one day, Lagos time.                                                                                          |
| Allocations per day          | ₦50,000,000              | The amount you allocate in one day, Lagos time.                                                                                                    |

## When you reach a limit

| Limit                        | Response                                  | What to do                                                                                                         |
| ---------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Requests per second          | `429 rate_limited`, with `Retry-After: 1` | Wait 1 second, then send the same request again. For a request that takes an `Idempotency-Key`, keep the same key. |
| Requests in progress at once | `429 rate_limited`, with `Retry-After: 1` | Wait 1 second, then send the same request again with the same key.                                                 |
| Order value per day          | `422 limit_exceeded`                      | Nothing was stored, so the key is still free. The limit resets at midnight, Lagos time.                            |
| Allocations per day          | `422 limit_exceeded`                      | Nothing was stored, so the key is still free. The limit resets at midnight, Lagos time.                            |

We refuse these requests before we store or send anything. `Retry-After` is the only rate limit header we send today. We don't send headers that show how much of a limit you have left.

## How order value is counted

Each order counts when you place it, at its quantity times a price per share:

| Order           | Price per share                                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Limit buy       | Its `price_kobo`.                                                                                                          |
| Any other order | The day's upper price limit for the symbol, which we ask the broker for when you place the order. Nothing trades above it. |

How much of an order still counts depends on its state:

| State                                  | Counts                                       |
| -------------------------------------- | -------------------------------------------- |
| `refused`                              | Nothing. It never reached the exchange.      |
| `rejected`, `cancelled`, `expired`     | Only the shares that filled before it ended. |
| Any other state, including `uncertain` | The whole order.                             |

## How allocations are counted

Every allocation created that day counts, except `rejected` and `refused` ones, whose amounts return to your wallet.

## Fixed limits

These are the same for every partner.

| What                                    | Limit                                            | Response                                                                         |
| --------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------- |
| Request body                            | 16 KiB                                           | `413 request_too_large`                                                          |
| `quantity` on an order                  | 1 to 100,000,000 shares                          | `400 invalid_request`, with `param` set to `quantity`                            |
| `price_kobo` on a limit order           | 1 to 1,000,000,000 kobo (₦10,000,000 a share)    | `400 invalid_request`, with `param` set to `price_kobo`                          |
| `symbol`                                | 20 characters: letters, digits, dots and hyphens | `400 invalid_request`, with `param` set to `symbol`                              |
| `amount_kobo` on one allocation         | 1 to 10,000,000,000 kobo (₦100,000,000)          | `400 invalid_request`, with `param` set to `amount_kobo`                         |
| Each application field                  | 200 bytes                                        | `400 invalid_request`, with `param` naming the field                             |
| `Idempotency-Key`                       | 255 bytes                                        | `400 invalid_request`, with `param` set to `Idempotency-Key`                     |
| `limit` on a list                       | 1 to 100, default 25                             | `400 invalid_request`, with `param` set to `limit`                               |
| Trades or contract notes in one request | 1,000 records                                    | `400 invalid_request`, with `param` set to `from`. Ask for a shorter date range. |

## Reads that ask the broker

Balances, positions, trades, contract notes and the reference lists are read from the broker each time you ask. Each partner can have 2 of these reads in progress at once, and at most 4 run at once across all partners. A read that can't start and finish within 20 seconds returns `503 exchange_unavailable`. Nothing was changed, so ask again shortly.