Handle a refused spend

Slen checks a model call of a flow against the limits you set: the budgets of the project and the credits of your customers. When one of them says no, the call is refused before the provider is called. This page is about catching that refusal and acting on it.

The family of a refused spend

A refusal of this kind is answered with the status 402. Both SDKs raise it as one family: SpendRefusedException in PHP and SpendRefusedError in Node.js, and each code has a type of its own that extends it. A 402 with a code the SDK has no type for is raised as the family type itself.

A policy that refuses is not part of the family. policy_denied and model_not_allowed are answered with 403 and raised as PolicyDeniedException or PolicyDeniedError — Policies says how a policy is checked. A blocked customer is refused the same way, with customer_blocked, as CustomerBlockedException or CustomerBlockedError, which extend the type of a policy refusal.

Two codes of the family, overrun_stopped and overrun_approval_required, come from the overrun policy of a model node in a flow, and such a policy practically never fires — their rows in the table above say why.

Catch it

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;
}

The code says which limit refused the call, and the table above says what to do about each.

• The refused call cost nothing: its provider was not called, and no money stays held for it. In a flow, the model calls of the nodes before it were paid for.

• The same request is refused again until something changes — a budget starts its next window, a limit is raised, the customer is topped up. concurrency_limit_exceeded is the exception: it passes once a running call ends.

• Do not send a refused request again in a loop.

The second form: an execution that ended rejected

A run is answered with the error once. The execution it opened is closed with the status rejected and keeps the code. Its cost.estimated is the estimate of the refused call — spend the refusal prevented, not money spent — or null when the refusal named no estimate, as for a customer out of credits. Whoever reads it later gets the execution and no error: a repeat of the request under its key, a wait, a status read, a run sent in async mode. So a run that you send again after a refusal goes under a new key.

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

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

When a model node has a branch on its Deny port, a refusal does not end the execution. The flow goes on along that branch and decides what the caller hears.

A Reject Request node may end an execution with any code, a code of this family too, and then no error is raised either. Code that reacts to a refusal handles both forms: the catch, and the status of what came back.

Where the limits are

• The budgets of a project are on Budgets.

• The credits of your customers are on Customers, and your application tops them up with customers.topUp() — Customers and credits.

• The policies are on Policies, in Settings.

Where to go next

• Handling errors — every error of the SDK, and whether it cost money.

• Error codes — what each code means and what to do about it.

• Async runs and waiting — how to read the way an execution ended.