Сборник рецептов по обработке ошибок

Что делает

Показывает каноническую форму обработки ошибок для вызывающих SDK:

1. SdkError — программная ошибка (например, вызов не-v3-метода через actions.v3.*).
2. AjaxError — REST вернул ошибку (ERROR_NOT_FOUND, INVALID_CREDENTIALS, EXPIRED_TOKEN, QUERY_LIMIT_EXCEEDED, …).
3. Сетевой уровень — NETWORK_ERROR / REQUEST_TIMEOUT. Критически отличается для неидемпотентных вызовов.
4. Soft-ошибки — коды, которые вы явно включили в возврат через softErrorCodes, чтобы вызов возвращал isSuccess: false вместо выброса.

Также охватывает setRestrictionManagerParams с новыми настройками:

• hardErrorCodes — расширить список SDK «выбрасывать сразу, без повтора» кодами вашего приложения.
• softErrorCodes — расширить список «возвращать как soft-ошибку в AjaxResult».
• retryOnNetworkError: false — отключить сетевой повтор для *.add / *.update / загрузок файлов, чтобы избежать дубликатов.

Стек

Node.js 18+. Без внешних зависимостей.

Переменные окружения

export B24_HOOK='https://your.bitrix24.com/rest/1/secret'

Запуск

npx tsx 10-error-handling.ts

Исходник

skills/b24jssdk-recipes/examples/10-error-handling.ts.

Примечания

• setRestrictionManagerParams обновляет политику для всех HTTP-клиентов на этом экземпляре $b24 (и v2, и v3).
• hardErrorCodes и softErrorCodes аддитивны — встроенные списки (коды авторизации/фатальные) всегда hard. Вы можете расширять, но не удалять.
• Для неидемпотентных вызовов предпочитайте оборачивать каждый вызов в try/finally, восстанавливающий retryOnNetworkError: true после. Рецепт показывает этот паттерн.
• Когда происходит сетевой таймаут для неидемпотентного вызова, безопасное действие — сверка (запросить только что созданную сущность по клиентскому тегу идемпотентности), а не повтор.