Errori

import { VimineError } from '@vimine/sdk';   // anche da /server

Tutto ciò che va storto arriva come VimineError, una sottoclasse di Error. code è l’identificativo stabile su cui ragionare: il code di un documento problem+json (RFC 9457), l’error di una risposta OAuth, o uno dei codici propri dell’SDK.

Proprietà

	Tipo
code	string	il codice stabile
message	string	il detail o title del problema, o error_description
status	number | null	lo stato HTTP, null per gli errori locali
requestId	string | null	il request_id della risposta: citalo nelle segnalazioni
detail	string | null	il detail del problema
errors	FieldError[] — { field?, code?, message? }	i dettagli di validation_failed e di identification_required; una voce codicefiscale_mismatch porta anche mismatches, hints e confirmable (guida)
cause	unknown	l’errore sottostante (network, framed)
isAuthError	boolean	true per «la sessione è finita: accedi di nuovo» (401, invalid_token, token_expired, missing_token, invalid_grant, not_signed_in)

I codici dell’SDK

code	Quando
invalid_options	costruttore senza clientId, redirectUri o clientSecret
network	la richiesta non ha raggiunto l’API (cause porta l’errore originale)
not_signed_in	nessuna sessione, o nessun refresh token, per una chiamata autenticata
no_flow	ritorno senza un accesso avviato da questo browser (storage vuoto o scaduto)
state_mismatch	il ritorno non corrisponde all’accesso avviato
framed	signIn() da un frame di un’altra origine
http_<stato>	risposta d’errore senza corpo JSON riconoscibile

I codici dell’API (insufficient_scope, not_found, validation_failed, statuto_required, rate_limited, …) e quelli OAuth (invalid_grant, access_denied, unauthorized_client, …) sono in Permessi, errori e limiti.

Gestirli

import { VimineError } from '@vimine/sdk';

try {
    await vimine.membership.acceptStatuto({ version });
} catch (err) {
    if (!(err instanceof VimineError)) throw err;
    if (err.isAuthError) return vimine.signIn({ returnTo: location.pathname });
    switch (err.code) {
        case 'statuto_outdated':  return alert(`È in vigore una versione più recente: ${err.detail}`);
        case 'insufficient_scope': return vimine.signIn({ scopes: ['statuto:accept'], prompt: 'consent' });
        case 'rate_limited':      return setTimeout(retry, 5000);
        default:                  console.error(err.code, err.requestId);
    }
}