Errors

Every failed request throws Anikeen\Id\Exceptions\ApiException – with the user's token as well as with the app's (app*()). It carries:

status	the HTTP status (also getCode()), 0 when Anikeen ID could not be reached
error	the stable error code when Anikeen ID sent one (e.g. billing_address_missing, already_cancelled), otherwise null
getMessage()	Anikeen ID's reason
isNotFound()	404
isConflict()	409
isTemporary()	no response, 429 or 5xx: retry later
isBillingLimitReached()	409 billing_limit_reached, see Charges
body()	the error response, for errors with details (e.g. net_amount of elapsed_amount_exceeded, remaining of billing_limit_reached)

use Anikeen\Id\Exceptions\ApiException;

try {
    $order = $user->orders()->create($attributes);
} catch (ApiException $e) {
    if ($e->isTemporary()) {
        return back()->with('error', 'Anikeen ID is not reachable right now, please try again.');
    }

    report($e);

    return back()->with('error', $e->getMessage());
}

Subclasses

Exception	Thrown for
ValidationFailedException	422; endpoints with codes per field fill errorCodes() (['username' => 'username_taken']), errorCodeFor($field) and hasErrorCode($code); errors() has the messages per field
PreconditionFailedException	412 of a conditional preference write, with currentVersion()
CollectionException	a failed list ($user->invoices(), …)

All three extend ApiException, so catching ApiException catches them too.

ConfirmationRequiredException – a third-party app called checkout() on a draft – is its own type; its confirmationUrl points to the page where the user confirms. All of them extend ResourceException, so existing catch (ResourceException $e) blocks keep working.

use Anikeen\Id\Exceptions\ValidationFailedException;

try {
    $profile = $user->updateProfile(['username' => 'erika']);
} catch (ValidationFailedException $e) {
    return back()->withErrors(match ($e->errorCodeFor('username')) {
        'username_taken' => ['username' => 'This username is taken.'],
        default => $e->errors(),
    });
}

Branch on the codes; the messages are for people and may change.