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

# Запросы, ответы и ошибки

> JSON, бинарные файлы, пагинация, идемпотентность, машинные коды ошибок и Retry-After.

## Форматы запроса

Для чтения используются и `GET`, и `POST`. Ориентируйтесь на описание метода. Например, [POST /personnel/profile](https://docs.arzguard.com/cerberus-crm/api/post-personnel-profile.md) читает карточку, а [PATCH /personnel/profile](https://docs.arzguard.com/cerberus-crm/api/patch-personnel-profile.md) её изменяет.

Для JSON указывайте `Content-Type: application/json`. [Загрузка доказательства](https://docs.arzguard.com/cerberus-crm/api/post-personnel-materials-upload.md) принимает байты PNG или JPEG в теле запроса. [Чтение доказательства](https://docs.arzguard.com/cerberus-crm/api/get-personnel-materials-id.md) возвращает PNG.

Для списков с курсором передавайте `next_cursor` в следующем запросе, сохраняя исходные фильтры. [История изменений профиля](https://docs.arzguard.com/cerberus-crm/api/post-personnel-changes.md) использует `offset` и `snapshot`.

## Изменения и повтор запроса

**1. Прочитайте актуальные данные**

У методов с подготовкой сначала запросите доступные варианты и `revision`. К примеру, [подготовьте кадровое действие](https://docs.arzguard.com/cerberus-crm/api/post-personnel-actions-options.md) перед его выполнением.

**2. Отправьте команду**

Передайте ревизию в указанном у метода поле. Если требуется `Idempotency-Key`, создайте отдельный ключ для операции и сохраните его вместе с телом запроса.

**3. Обработайте результат**

При сетевом сбое повторите ту же операцию с тем же ключом и телом. При конфликте ревизии перечитайте данные и проверьте действие перед новой отправкой.

## Формат ошибок

Ответы об ошибках содержат машинный `code`. Если в ответе есть `correlation_id` или заголовок `X-Correlation-ID`, сохраните его для диагностики.

```json Условный ответ HTTP 401 theme={null}
{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A valid partner token is required.",
  "instance": "/api/partner/v1/servers",
  "code": "partner_unauthenticated"
}
```

| HTTP | Что сделать |
| - | - |
| `400`, `422` | Проверить параметры, формат и обязательные поля. |
| `401` | Проверить токен, окружение и разрешённый IP. |
| `403` | Проверить scope, согласованный сервер, trust и полномочия модератора. |
| `404` | Проверить идентификатор и видимость цели в выбранном контексте. |
| `409` | Проверить причину конфликта, версию записи или повторное использование ключа. |
| `413` | Проверить размер тела или файла по ограничениям метода. |
| `429` | Подождать указанное в `Retry-After` число секунд. При повторных ограничениях увеличивать задержку. |
| `5xx` | Повторить по политике клиента. Для операций записи сохранить ключ повтора. |

Актуальные лимиты разработчика, бота и операций можно прочитать через [GET /me](https://docs.arzguard.com/cerberus-crm/api/get-me.md). Прокси может вернуть ошибку с телом другого формата. Обрабатывайте HTTP-статус до разбора JSON.


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