Обработайте отклонённую трату

Slen проверяет вызов модели во флоу по лимитам, которые вы задали: по бюджетам проекта и по кредитам ваших клиентов. Когда один из них говорит «нет», вызов отклоняется до обращения к провайдеру. Эта страница — о том, как поймать такой отказ и что с ним делать.

Семейство отклонённой траты

На такой отказ отвечают статусом 402. Оба SDK выбрасывают такие отказы как одно семейство ошибок: SpendRefusedException в PHP и SpendRefusedError в Node.js, и у каждого кода есть свой тип, который расширяет тип семейства. 402 с кодом, для которого у SDK нет типа, выбрасывается как сам тип семейства.

Политика, которая отказывает, в семейство не входит. На policy_denied и model_not_allowed отвечают 403 и выбрасывают их как PolicyDeniedException или PolicyDeniedError — как проверяется политика, говорит статья Политики. Запрос для заблокированного клиента отклоняется так же, с customer_blocked, как CustomerBlockedException или CustomerBlockedError, которые расширяют тип отказа политики.

Два кода семейства, overrun_stopped и overrun_approval_required, приходят от политики перерасхода узла модели во флоу, а такая политика практически не срабатывает — почему, говорят их строки в таблице выше.

Поймать его

use Slen\Sdk\Exceptions\OperationUncertainException;
use Slen\Sdk\Exceptions\SlenException;
use Slen\Sdk\Exceptions\SpendRefusedException;
use Slen\Sdk\Modules\Operations\Options\ExecuteOptions;

$input = ['messages' => [['role' => 'user', 'content' => 'Write a short follow-up email.']]];

try {
    $execution = $slen->operations()->execute('generate_email', $input, new ExecuteOptions(idempotencyKey: 'order-42:email'));

    echo $execution->status->value, PHP_EOL;
} catch (SpendRefusedException $error) {
    // The spend was refused, and the code says what refused it.
    echo 'refused: ', $error->errorCode, PHP_EOL;
} catch (OperationUncertainException $error) {
    // A provider was called and its answer was lost: the call may have been paid for.
    echo 'uncertain, request ', $error->requestId, PHP_EOL;
} catch (SlenException $error) {
    echo $error->statusCode, ' ', $error->errorCode, ': ', $error->getMessage(), PHP_EOL;
}

Код говорит, какой лимит отклонил вызов, а таблица выше — что делать с каждым.

• Отклонённый вызов ничего не стоил: его провайдер не вызывался, и за него не остаётся зарезервированных денег. Во флоу вызовы моделей в узлах до него оплачены.

• Тот же запрос отклоняется снова, пока что-то не изменится: бюджет начнёт следующее окно, лимит поднимут, клиента пополнят. Исключение — concurrency_limit_exceeded: он проходит, как только идущий вызов закончится.

• Не отправляйте отклонённый запрос снова в цикле.

Вторая форма: выполнение, которое закончилось отказом

На запуск отвечают ошибкой один раз. Выполнение, которое он открыл, закрывается со статусом rejected и хранит код. Его cost.estimated — оценка отклонённого вызова, то есть трата, которую отказ предотвратил, а не потраченные деньги, — или null, когда отказ не назвал оценки, как для клиента без кредитов. Тот, кто читает его позже, получает выполнение, а не ошибку: повтор запроса под его ключом, ожидание, чтение статуса, запуск, отправленный в асинхронном режиме. Поэтому запуск, который вы отправляете снова после отказа, идёт под новым ключом.

$again = $slen->operations()->execute('generate_email', $input, new ExecuteOptions(idempotencyKey: 'order-42:email'));

if ($again->isRejected()) {
    echo 'rejected: ', $again->errorCode, PHP_EOL;
}

Когда у узла модели есть ветка на порту Отказ, отказ не заканчивает выполнение. Флоу продолжает путь по этой ветке и решает, что услышит вызывающий.

Узел Отклонить запрос может закончить выполнение с любым кодом, в том числе с кодом этого семейства, и тогда ошибка тоже не выбрасывается. Код, который реагирует на отказ, обрабатывает обе формы: catch и статус того, что вернулось.

Где лимиты

• Бюджеты проекта — на странице Бюджеты.

• Кредиты ваших клиентов — на странице Клиенты, а пополняет их ваше приложение через customers.topUp() — Клиенты и кредиты.

• Политики — на странице Политики, в разделе Настройки.

Что читать дальше

• Обработка ошибок — каждая ошибка SDK и стоила ли она денег.

• Коды ошибок — что значит каждый код и что с ним делать.

• Асинхронные запуски и ожидание — как прочитать, чем закончилось выполнение.