Оформление
Ошибки и безопасные повторы
Проверяйте HTTP status и error.code, а не только текст сообщения. Сообщение помогает человеку; code удобнее для программы.
json
{
"error": {
"code": "STALE_REVISION",
"message": "Stale revision",
"correlationId": "CORRELATION_ID",
"details": {}
}
}Что делать с кодом ответа
| HTTP | Значение | Действие |
|---|---|---|
| 400 | Неверный JSON, параметр или данные | Исправить запрос по схеме |
| 401 | Ключ не принят | Проверить ключ, срок и владельца |
| 403 | Недостаточно прав | Проверить scope и права владельца |
| 404 | Ресурс не найден или недоступен | Проверить ID и доступ |
| 409 | Ревизия, состояние или ключ повтора конфликтуют | Прочитать актуальные данные и сверить намерение |
| 413 | Слишком большое тело | Уменьшить запрос; общий JSON-предел 10 MiB |
| 422 | Workflow отклонил действие | Проверить переход, условия и обязательные поля |
| 429 | Превышен лимит | Отложить запрос и уменьшить параллелизм |
| 500 | Внутренняя ошибка | Сохранить correlationId; не повторять изменение вслепую |
Безопасные повторы
Idempotency-Key поддержан для создания объекта, связи, комментария, вложения, заявки каталога и входящей интеграции. Для PATCH, imports/run и bulk универсального такого механизма нет.
Выберите устойчивый ключ операции длиной 8–128 символов: буквы, цифры, ., _, :, -. При сетевом повторе отправьте тот же ключ и то же тело. Другой payload с прежним ключом вернёт HTTP 409.
Сохранённый ответ имеет срок 24 часа. Если receipt уже истёк, сервер возвращает конфликт: сначала найдите результат исходной операции. Не создавайте новый ключ, пока не убедитесь, что действие не выполнилось.
После изменения прав повтор сохранённого ответа может быть запрещён. Это не сигнал повторно создать объект — перечитайте его с актуальными правами.
Лимиты и журнал
По умолчанию допускается 120 запросов на ключ за минутное окно. Успешная аутентификация возвращает X-RateLimit-Limit и X-RateLimit-Remaining. При превышении квоты в details может быть retryAfterSeconds:60. Не рассчитывайте, что каждый ответ HTTP 429 обязательно содержит Retry-After: отдельный предел защищает параллельную проверку ключей.
Если успешный ответ содержит X-NGENSIA-Operation-Warning, сохраните его вместе с correlationId и обратитесь к администратору. Предупреждение о журнале не означает, что команду нужно повторить.