Обработка ошибок

При использовании YDB SDK возникают ситуации, в которых необходимо обрабатывать ошибки.

Ошибки можно разделить на три категории:

• Временные сбои (retryable, далее R) — включают в себя кратковременную потерю сетевого соединения, временную недоступность или перегруженность одной из подсистем YDB, неспособность YDB ответить на запрос в течение установленного времени ожидания. В случае возникновения таких ошибок, повтор запроса, завершившегося с ошибкой, через некоторый промежуток времени с большой вероятностью будет выполнен успешно.

• Ошибки, которые не могут быть исправлены с помощью повтора (non retryable, далее N) — включают в себя некорректно сформированные запросы, внутренние ошибки YDB, запросы, несоответствующие схеме данных. В такой ситуации нет необходимости повторять запрос, требуется дополнительное вмешательство со стороны разработчика.

• Ошибки, которые, предположительно, могут быть исправлены с помощью повтора после реакции клиентского приложения (conditionally retryable, далее C) — включают в себя отсутствие ответа в течение отведенного времени, запрос аутентификации.

YDB SDK предоставляет встроенный механизм обработки временных сбоев. По умолчанию в SDK используется рекомендованная политика повторов, которую можно изменить в соответствии с требованиями клиентского приложения. YDB возвращает коды завершения, которые позволяют определить, уместна ли повторная попытка и какой выбрать интервал.

Операции следует повторять только в том случае, когда ошибки являются временными сбоями. Не пытайтесь выполнить повторно недопустимые операции, такие как вставка в таблицу строки с существующим значением первичного ключа или вставка данных несоответствующих схеме таблицы.

Крайне важно оптимизировать число повторных попыток и интервал между ними. Чрезмерное количество повторных попыток и слишком короткий интервал между ними создают избыточную нагрузку. Недостаточное количество повторных попыток не позволит завершить выполнение операции.

При выборе интервала обычно используются следующие стратегии:

• Экспоненциальная задержка. Для каждой последующей попытки интервал увеличивается по экспоненциальному закону.
• Интервалы с приращениями. Для каждой последующей попытки интервал увеличивается с определенными приращениями.
• Постоянные интервалы. Повторные попытки совершаются через одинаковые интервалы.
• Немедленный повтор. Повторные попытки совершаются немедленно.
• Случайный выбор. Повторные попытки совершаются через случайно выбранный интервал времени.

При выборе интервала и числа повторных попыток учитывайте статусы завершения YDB.

Не используйте бесконечные повторные попытки. Это может привести к возникновению избыточной нагрузки.

Не выполняйте немедленный повтор больше одного раза.

Журналирование ошибок

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

• Журналируйте количество предпринимаемых повторных попыток. Увеличение числа регулярных повторных попыток часто указывает на наличие проблем.
• Журналируйте все ошибки, в том числе их типы, коды завершения и причины, вызывающие их появление.
• Журналируйте общее время выполнения операций, в том числе завершающихся после повторного выполнения.

Статусы завершения

Ниже приведены статусы завершения которые можно получить при работе с SDK.

Типы ошибок:

• R (retryable) — временные сбои
• N (non retryable) — ошибки, которые не могут быть исправлены с помощью повтора
• С (conditionally retryable) — ошибки, которые предположительно могут быть исправлены с помощью повтора после реакции клиентского приложения

Статус	Описание	Реакция	Тип
SUCCESS	Запрос успешно обработан	Продолжить выполнение
BAD_REQUEST	Ошибка в синтаксисе запроса, пропущены обязательные поля	Проверить запрос	N
INTERNAL_ERROR	Неизвестная внутренняя ошибка	Связаться с разработчиками	N
ABORTED	Операция не выполнена (например, по причине инвалидации локов, KIKIMR_LOCKS_INVALIDATED в подробных сообщениях об ошибке)	Повторить всю транзакцию	R
UNAUTHENTICATED	Требуется аутентификация.	Проверить использующийся токен. С актуальным токеном повторить запрос.	N
UNAUTHORIZED	Отсутствует доступ к запрашиваемому объекту (таблица, директория)	Запросить доступ у администратора БД.	N
UNAVAILABLE	Часть системы недоступна	Повторить последнее действие (запрос)	R
UNDETERMINED	Состояние транзакции неизвестно. В результате выполнения запроса произошёл сбой, из-за которого невозможно определить состояние транзакции. На запросы, завершившиеся с таким статусом, распространяются гарантии целостности и атомарности транзакции. То есть либо все изменения зафиксированы, либо вся транзакция отменена.	Для идемпотентных транзакций можно повторить всю транзакцию с небольшой задержкой. В противном случае реакция зависит от логики приложения.	C
OVERLOADED	Часть системы перегружена	Повторить последнее действие (запрос), снизить интенсивность запросов	R
SCHEME_ERROR	Запрос не соответствует схеме	Исправить запрос или схему	N
GENERIC_ERROR	Неклассифицируемая ошибка, возможно, связанная с запросом	Посмотреть на подробное сообщение об ошибке, связаться с разработчиками	N
TIMEOUT	Запрос не выполнен за отведенное время	Можно повторить для идемпотентных запросов	C
BAD_SESSION	Данная сессия больше недоступна	Пересоздать сессию	N
PRECONDITION_FAILED	Запрос не может быть выполнен для данного состояния (например, вставка в таблицу с существующим ключом)	Исправить состояние или запрос и повторить	C
TRANSPORT_UNAVAILABLE	Транспортная ошибка, endpoint недоступен или разрыв соединения, с невозможностью его переустановить	Проверить endpoint или другие настройки сети	C
CLIENT_RESOURCE_EXHAUSTED	Недостаточно свободных ресурсов для обслуживания запроса	Снизить интенсивность запросов, проверить клиентскую балансировку	R
CLIENT_DEADLINE_EXCEEDED	Запрос не был обработан за заданный клиентский таймаут, иная сетевая проблема	Проверить корректность заданного таймаута, наличие сетевого доступа, проверить endpoint или другие настройки сети снизить интенсивность запросов, оптимизировать запросы	C