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

# Ошибки и лимиты запросов Apex

> Все ошибки OrbitFlare Apex: коды JSON-RPC -32001, -32029, -32602 и -32603, статусы простых HTTP-маршрутов, коды допуска QUIC, лимиты запросов и что делать в каждом случае.

## Принята не значит попала в блок

Успешный ответ означает, что эндпоинт Apex получил вашу транзакцию и отправляет её лидерам наперегонки, пока она не попадёт в блок или пока не истечёт её blockhash. Он **не** означает, что транзакция попала в блок. Подтверждайте каждую отправку через `getSignatureStatuses` на Solana RPC. См. [Лучшие практики](/ru/apex/best-practices#подтверждайте-каждую-отправку).

Apex проверяет транзакцию в таком порядке: API-ключ, лимит запросов, корректность и размер транзакции, затем чаевые. Ошибку определяет первая непройденная проверка. Пока не пройдены все проверки, ничего никуда не отправляется, поэтому отклонённая транзакция ничего не стоит.

## Ошибки JSON-RPC

| Код      | Значение                                                                                                                  | Что делать                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `-32001` | Не авторизовано. API-ключ отсутствует или недействителен                                                                  | Проверьте заголовок `x-api-key` или параметр `?api-key=`                        |
| `-32029` | Превышен лимит запросов. Ваш ключ превысил свой лимит в секунду                                                           | Сделайте короткую паузу и повторите. Сглаживайте всплески                       |
| `-32602` | Некорректная транзакция или чаевые. В сообщении указано, что именно не так, а при недостаточных чаевых указан ваш минимум | Исправьте транзакцию. Повторная отправка тех же байтов снова завершится ошибкой |
| `-32603` | Занято. Эндпоинт сбрасывает нагрузку                                                                                      | Повторите после короткой задержки или переключитесь на другой эндпоинт Apex     |

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "..."
  }
}
```

## Ошибки простых HTTP-маршрутов

На `/send` и `/send-bin` успехом считается HTTP `200` с `{"signature": "..."}`. `/send-batch` отвечает `200` с `{"attempted": n, "accepted": n, "rejected": n, "results": [...]}`, где каждый результат, в порядке фреймов, представляет собой либо `{"signature": "..."}`, либо `{"error": "<label>", "message": "..."}`. `/send-bundle` отвечает `200` с `{"bundle_id": "...", "signatures": ["...", "..."]}`.

Ошибки возвращаются в JSON с машиночитаемой меткой и понятным человеку сообщением:

```json theme={null}
{ "error": "<label>", "message": "..." }
```

| Статус | Значение                                   | Метки                                                                                                                                               |
| ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Не авторизовано                            | `unauthorized`                                                                                                                                      |
| `429`  | Превышен лимит запросов                    | `rate_limited`                                                                                                                                      |
| `400`  | Некорректный запрос, транзакция или чаевые | `invalid`, `malformed`, `no_signatures`, `no_tip`, `below_floor`, `multiple_tips`, `tip_not_static`, `tip_source_not_signer`, `too_large`, `bundle` |
| `408`  | Тело запроса не получено за 2 секунды      | `timeout`                                                                                                                                           |
| `413`  | Тело запроса слишком большое               | `too_large`                                                                                                                                         |
| `503`  | Занято                                     | `busy`                                                                                                                                              |

<Note>
  Сначала ветвите логику по HTTP-статусу. Это стабильная часть контракта. Незнакомую метку при статусе `400` трактуйте как «исправьте транзакцию».
</Note>

`/send-batch` отвечает `200` всякий раз, когда сам запрос сформирован правильно, и сообщает о каждом фрейме отдельно внутри `results`. Проверяйте `rejected` и каждую запись, а не только код статуса. См. [POST /send-batch](/ru/apex/sending-transactions#post-/send-batch).

Метка `bundle` (HTTP `400`) означает, что [бандл](/ru/apex/bundles) отклонён целиком: в нём больше 4 участников, есть повторяющийся участник, бандлы недоступны для этого ключа или эндпоинта либо его отклонил block engine. Проблема отдельного участника сохраняет собственную метку. Участник больше 1232 байт возвращается как `malformed` с сообщением, в котором назван лимит 1232 байта, два участника с чаевыми дают `multiple_tips`, а отсутствие участника с чаевыми даёт `no_tip`.

### Ошибки чаевых подробно

| Метка                   | Что пошло не так                                                                | Исправление                                                                             |
| ----------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `no_tip`                | Нет перевода SystemProgram верхнего уровня на опубликованный аккаунт для чаевых | Добавьте [инструкцию чаевых](/ru/apex/tips). Перевод, сделанный через CPI, не считается |
| `below_floor`           | Чаевые ниже минимума вашего тарифа. В сообщении указан минимум                  | Поднимите чаевые как минимум до этого минимума                                          |
| `multiple_tips`         | Больше одного перевода чаевых                                                   | Оставьте ровно один                                                                     |
| `tip_not_static`        | Аккаунт для чаевых был загружен через address lookup table                      | Поместите аккаунт для чаевых в статические ключи аккаунтов                              |
| `tip_source_not_signer` | Аккаунт, который платит чаевые, не подписал транзакцию                          | Оплачивайте чаевые с аккаунта подписанта                                                |

## Коды допуска QUIC

Двунаправленный QUIC-поток отвечает одним кодом допуска. Однонаправленный поток ничего не возвращает, поэтому на время интеграции используйте двунаправленный поток.

| Код | Имя              | `AdmissionCode` в Rust | Эквивалент в JSON-RPC |
| --- | ---------------- | ---------------------- | --------------------- |
| `0` | ok               | `Ok`                   | result                |
| `1` | unauthorized     | `Unauthorized`         | `-32001`              |
| `2` | rate limited     | `RateLimited`          | `-32029`              |
| `3` | invalid          | `Invalid`              | `-32602`              |
| `4` | no tip           | `NoTip`                | `-32602`              |
| `5` | below floor      | `BelowFloor`           | `-32602`              |
| `6` | busy             | `Busy`                 | `-32603`              |
| `7` | malformed packet | `MalformedPacket`      | нет                   |

Если отклонено само **рукопожатие** QUIC, соединение закрывается с ошибкой приложения `1` (нет клиентского сертификата), `2` (неизвестный ключ) или `3` (слишком много соединений). См. [Аутентификация](/ru/apex/authentication#quic-клиентский-сертификат).

В клиенте на Rust `send_transaction_with_response` превращает отклонение в `Error::Rejected { code, message }`, а транзакция больше 4096 байт завершается локальной ошибкой `Error::TooLarge` до того, как что-либо будет отправлено.

## Какие ошибки повторять

| Ошибка                                               | Повторять?                                                                                          |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Превышен лимит запросов (`-32029`, `429`)            | Да, после короткой паузы                                                                            |
| Занято (`-32603`, `503`)                             | Да, после короткой задержки или на другом эндпоинте Apex                                            |
| Сетевая ошибка или тайм-аут до получения ответа      | Да. Эндпоинт отсеивает дубликаты по подписи, поэтому повторная отправка той же транзакции безопасна |
| Некорректная транзакция или чаевые (`-32602`, `400`) | Нет. Соберите транзакцию заново                                                                     |
| Не авторизовано (`-32001`, `401`)                    | Нет. Исправьте ключ                                                                                 |

**Принятую** транзакцию отправлять повторно не нужно. Apex уже повторяет её отправку, пока она не попадёт в блок или пока не истечёт blockhash. Если к этому моменту она не попала в блок, соберите её заново со свежим blockhash и отправьте новую транзакцию.

## Лимиты запросов

Лимиты запросов действуют **на каждый API-ключ** и задаются **тарифом** ключа. Лимит считает транзакции в секунду по всем транспортам: JSON-RPC, HTTP-маршруты и QUIC расходуют одну и ту же квоту, а каждый фрейм пакета считается одной транзакцией.

При превышении лимита вы получаете `-32029`, HTTP `429` или код допуска `2`. Отклонённая транзакция не ставится в очередь, поэтому отправьте её снова чуть позже, если она всё ещё важна.

Лимит и минимум чаевых вашего тарифа показаны рядом с ключом в [панели управления OrbitFlare](https://orbitflare.com/dashboard) в разделе **Dashboard > Apex**. Чтобы повысить их, свяжитесь с командой в [Discord](https://discord.gg/orbitflare).

## Ограничения вкратце

| Ограничение           | Значение                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------ |
| Размер транзакции     | Legacy и v0: 1232 байта. [v1](/ru/apex/transaction-v1): 4096 байт                          |
| Размер пакета         | 16 транзакций на запрос `/send-batch`                                                      |
| Размер бандла         | От 1 до 4 транзакций, по 1232 байта каждая                                                 |
| Размер пакета QUIC    | 4160 байт                                                                                  |
| Соединения QUIC       | 128 на API-ключ, 64 на адрес                                                               |
| Тайм-аут простоя QUIC | 30 секунд. Клиент на Rust отправляет пинг каждую секунду                                   |
| Соединения            | Достаточно одного QUIC-клиента на процесс и эндпоинт Apex. Потоки мультиплексируются в нём |