Errors

#How errors work

When Rekhu refuses a call, the core package throws. Every refusal is one base class with a class of its own under it, so you catch exactly what you handle:

• Laravel: Rekhu\Core\Exceptions\RekhuException, with the classes under Rekhu\Core\Exceptions.
• Node.js: RekhuError, with the classes exported from @rekhu/core.

Each carries status (the HTTP status Rekhu gave, or 0 when the call was not made) and type (Rekhu's error type), and a message that says what was wrong.

#The error types

UnsafeFile carries safety, and LimitReached carries scope. Both extend the base class, so a catch of the base class catches them too.

#Catch what you handle

use Rekhu\Core\Exceptions\CreditExhausted;
use Rekhu\Core\Exceptions\InvalidRequest;
use Rekhu\Core\Exceptions\LimitReached;
use Rekhu\Core\Exceptions\RekhuException;
use Rekhu\Core\Exceptions\UnsafeFile;
use Rekhu\Core\Rekhu;

try {
    $check = Rekhu::seshat()->for($user)->check($request->file('artwork'), $order);
} catch (UnsafeFile $e) {
    return back()->withErrors(['artwork' => $e->getMessage()]);       // $e->safety holds the report
} catch (LimitReached $e) {
    return back()->withErrors(['artwork' => 'Today\'s checks are used up.']);   // $e->scope: tenant or user
} catch (InvalidRequest $e) {
    report($e);                                                          // a mistake in the order or the fixes
    throw $e;
} catch (CreditExhausted $e) {
    Log::critical('Rekhu credit is used up');
    return back()->withErrors(['artwork' => 'Checking is not available right now.']);
} catch (RekhuException $e) {
    Log::error('Rekhu refused', ['status' => $e->status, 'type' => $e->type, 'message' => $e->getMessage()]);
    throw $e;
}

import { CreditExhausted, InvalidRequest, LimitReached, RekhuError, UnsafeFile } from '@rekhu/core';

try {
    const check = await rekhu.seshat({ user }).check(buffer, { name: 'flyer.pdf', order });
    res.json(check);
} catch (error) {
    if (error instanceof UnsafeFile) return res.status(422).json({ message: error.message, safety: error.safety });
    if (error instanceof LimitReached) return res.status(429).json({ message: 'Today\'s checks are used up.', scope: error.scope });
    if (error instanceof InvalidRequest) throw error;               // a mistake in the order or the fixes
    if (error instanceof CreditExhausted) {
        logger.error('Rekhu credit is used up');
        return res.status(503).json({ message: 'Checking is not available right now.' });
    }
    if (error instanceof RekhuError) logger.error('Rekhu refused', { status: error.status, type: error.type, message: error.message });
    throw error;
}

Catch the specific classes before the base class: the first catch that matches wins.

#Retries and double charges

The packages try a call again by themselves, so most short failures never reach your code:

1. When Rekhu cannot be reached. A dropped connection, or a 502, 503 or 504 that does not come from Rekhu itself (for example for a moment while Rekhu is being updated), is tried up to four times, waiting 2, 4 and 8 seconds.
2. When Rekhu is busy. A 429 or 529, or an answer of type overloaded_error or rate_limit_error, is tried up to three times, waiting as long as Rekhu's retry-after asks, up to 5 seconds.
3. What is not. Every other failure is thrown at once as the class for it.
4. No double charges. Every charged call carries an idempotency key. When a retry reaches Rekhu after the first call already ran, Rekhu answers the first result again, with meta.replayed, and charges nothing.
5. Parts of a large file. Each part of an upload in parts is sent again up to three times on its own. When it still fails, resume the upload; see Large files.

#What is never charged

A refused call costs nothing: an InvalidRequest, an UnsafeFile, a ModuleNotEnabled, and a LimitReached, which is never sent. A fix with nothing to do is not charged either.

#Errors in the assistant

The assistant packages handle Rekhu's refusals themselves. When the project's assistant is paused, at its monthly limit, or out of credit, your users read that the assistant is not available right now, and your app's log says why. In Laravel, php artisan rekhu:assistant checks the key and the credit; in Node.js, assistant.check() does.

The chat routes answer errors as JSON with a message:

The widget shows the message, and asks the user to reload on 401 and 419.

#Next

• The core package: install, configuration and the ledger.
• File safety: the safety report behind UnsafeFile.