Risposte ed errori

Leggi stati HTTP, campi della risposta e codici di errore stabili, poi decidi se correggere, riprovare o fermarti.

Gli errori delle API della rubrica usano un oggetto error con code e message. Gestisci lo stato HTTP ed error.code. Il messaggio inglese spiega l’errore corrente e può cambiare; non interpretarlo come un contratto.

json

{
  "error": {
    "code": "invalid_parameter",
    "message": "Supply exactly one lookup parameter"
  }
}

Una richiesta riuscita può dare un verdetto negativo#

HTTP 200 indica che la richiesta di verifica è stata elaborata. valid uguale a false è un risultato della verifica. Leggi reason e signatureOk prima di accettare il messaggio. Allo stesso modo, la disponibilità di un alias può restituire 200 con available=false e una scheda completa può avere proof=null quando la verifica corrente del registro non è disponibile.

Correggere e riprovare le richieste#

400, 413 e 422 richiedono dati corretti. Inviare di nuovo gli stessi byte non li corregge.
401 e 403 richiedono credenziali, firma, permessi o ruolo validi. Una chiave API non valida non attiva l’accesso anonimo.
409 richiede una nuova lettura dello stato corrente. Controlla se la scrittura precedente è già riuscita prima di firmare un’altra operazione.
Per rate_limited e busy, attendi i secondi di Retry-After. Per errori temporanei delle letture usa attese crescenti con variazione casuale e un limite. Non ripetere alla cieca una scrittura firmata; leggi prima la scheda o lo stato dell’operazione, poi usa nuovi nonce e firma se serve.

Schede cancellate#

HTTP 410 con error.code erased restituisce anche erased=true, n, closedAt, token e logIndexes. Una rimozione dello staff aggiunge removed=true, category e, quando disponibile, logIndex. È una ricevuta storica; non ripristina l’autorità della scheda. Anche proof_expired per una prova temporanea usa 410 e contiene soltanto l’involucro di errore ordinario.

Tipi di contenuto e risposte vuote#

Leggi Content-Type prima di interpretare il corpo. Immagini, script, note firmate del registro e tessere non sono JSON. Una lettura condizionale della documentazione o di una scheda può restituire 304 senza corpo. Riusa la rappresentazione salvata con il suo ETag. Il callback OAuth mostra una pagina HTML anche in caso di errore. Le risorse di log.veil.rip usano un proprio protocollo testuale o binario e non garantiscono l’involucro di errore della rubrica. Anche un proxy o CDN può restituire un errore HTML; gestisci gli errori di lettura del JSON.

Codici di errore#

Cerca un codice, stato o spiegazione

HTTP	Codice	Significato e cosa fare
400	`bad_request`	La richiesta HTTP non è leggibile. Controlla la codifica e il corpo.
400	`hash_needed`	La firma copre un hash del file che la richiesta non porta. Il messaggio comincia con il suo nome: sha256, sha512 o blake2b512. Calcola quell’hash del file (sha256sum, sha512sum o b2sum) e mandalo nel campo con lo stesso nome.
400	`invalid_alias`	L’alias non rispetta le regole ASCII del nome. Usa da 3 a 32 lettere ASCII minuscole, cifre, trattini o trattini bassi; inizia con una lettera e termina con una lettera o cifra.
400	`invalid_block`	Il blocco firma non è leggibile o indica un’altra rubrica. Incolla il blocco completo con il messaggio e usa la rubrica che indica.
400	`invalid_file_signature`	La firma di un file o di un elenco di checksum non si legge. Il messaggio comincia con il motivo: unreadable, namespace (una firma SSH fatta per un uso diverso dai file), pgp_type, pgp_version, weak_hash, list_unreadable o block_message. Manda il file della firma come l’ha scritto lo strumento. Firma i file con ssh-keygen -Y sign -n file, gpg --detach-sign con SHA-256 o SHA-512, oppure minisign -Sm.
400	`invalid_json`	Il corpo non è un oggetto JSON, contiene chiavi duplicate o dati finali. Invia un solo oggetto JSON valido con `Content-Type` application/json.
400	`invalid_name`	Un nome contiene caratteri invisibili, controlli di direzione o caratteri di formato non ammessi. Usa un nome visibile nella forma Unicode ammessa e firma la richiesta corretta.
400	`invalid_nonce`	Il nonce della richiesta firmata ha un formato errato. Genera un nuovo nonce da 16 a 128 caratteri usando lettere, cifre, _ o -.
400	`invalid_parameter`	Un campo del percorso, della query o del corpo manca, è malformato o fuori intervallo. Correggi il campo indicato in `error.message` prima di inviare di nuovo.
400	`invalid_signature_alg`	`X-Signature-Alg` non è supportato. Usa un algoritmo di firma supportato e la codifica corretta per chiave e firma.
400	`invalid_timestamp`	Il timestamp della richiesta firmata non è espresso in millisecondi Unix. Usa un timestamp Unix intero in millisecondi e firma la richiesta corretta.
400	`wrong_format`	La richiesta o la lettura appartiene all’altro formato del registro di questo server: un record v1 su un registro in formato 2, o una lettura del formato 2 su un registro in formato 1. Leggi `format` in GET /v1/log (assente vuol dire 1) e manda la forma di quel formato.
401	`invalid_api_key`	La credenziale Bearer è malformata, sconosciuta, scaduta o revocata. Usa una chiave attiva. Per l’accesso pubblico anonimo, rimuovi del tutto `Authorization`. Credenziali non valide non attivano automaticamente l’accesso anonimo.
401	`invalid_signature`	La firma della richiesta HTTP non è valida. Firma metodo, percorso e byte del corpo esatti, senza modificarli dopo.
401	`missing_signature`	La richiesta richiede una firma del dispositivo e le intestazioni mancano o non sono leggibili. Invia `X-Public-Key`, `X-Signature` e i metadati della richiesta firmata. Una chiave API non sostituisce la firma del dispositivo.
401	`stale_timestamp`	Il timestamp firmato è fuori dalla finestra temporale ammessa. Confronta l’intestazione Date del server con il tuo orologio, poi genera nuovi nonce, timestamp e firma.
403	`api_key_scope`	La chiave API non ha il permesso read o verify, oppure l’endpoint non accetta chiavi Bearer. Usa il permesso corretto. Le modifiche alle schede e la gestione delle chiavi richiedono una firma del dispositivo.
403	`api_key_suspended`	Questa chiave API è sospesa. Chiedi allo staff di ripristinarla; un’altra chiave non rimuove la sospensione dell’account.
403	`cors_not_allowed`	Un preflight del browser richiede un metodo o un’intestazione fuori dal CORS pubblico. Usa dal browser le letture pubbliche anonime o la verifica. Mantieni le credenziali Bearer e di firma nei flussi locali o server supportati.
403	`developer_suspended`	L’account API del titolare è sospeso oppure la scheda titolare non è disponibile. Controlla l’account titolare e le restrizioni dello staff. Creare un’altra chiave non aggira la sospensione.
403	`identity_banned`	La scheda che agisce è sospesa dallo staff di Veil. Attendi la fine della restrizione o chiedi allo staff di riesaminarla.
403	`invalid_token`	Il token del link non è la firma del server per questa scheda. Copia il link intero dall’email, oppure togli gli avvisi dalla pagina dell’account.
403	`key_banned`	La chiave del dispositivo che firma è sospesa dallo staff di Veil. Usa una chiave attiva autorizzata o chiedi allo staff di riesaminare la restrizione.
403	`key_mismatch`	La chiave di firma non è autorizzata per questa scheda o operazione. Usa una chiave di dispositivo attiva con il ruolo di titolare o membro richiesto.
403	`recovery_key_only`	Un’operazione riservata al recupero è stata firmata con un altro ruolo. Usa la chiave di recupero nel flusso documentato.
403	`role_not_allowed`	Il ruolo che firma non può eseguire questa modifica. Usa una chiave con il ruolo richiesto.
403	`signer_not_authorised`	Il membro dell’organizzazione o il ruolo di firma non può pubblicare questa modifica. Controlla l’affiliazione accettata e il ruolo richiesto per la modifica.
404	`not_found`	La scheda, la chiave, l’alias, il codice o la risorsa richiesti non sono stati trovati. Controlla l’identificatore. Codici e anteprime temporanei potrebbero essere scaduti o già usati.
409	`account_locked`	La moderazione impedisce di richiedere questo account. Controlla lo stato pubblico di moderazione della scheda corrente.
409	`action_pending`	Un avviso precedente sullo stesso account, o un’azione dello staff della stessa famiglia, aspetta ancora il registro. Riprova quando è pubblicato, entro qualche minuto.
409	`alert_in_force`	L’account ha già questo stesso avviso. Non serve altro. Per correggere la data o il nuovo account, manda l’avviso con i dati nuovi.
409	`alert_not_in_force`	`regained` chiude un avviso, e l’account non ne ha uno in vigore. Leggi gli avvisi della scheda (GET /v1/identities/{n}/alerts) prima di chiuderne uno.
409	`alias_quarantined`	L’alias è nei 30 giorni di quarantena dopo il rilascio. Leggi `reusableAt` e il titolare precedente tramite l’endpoint degli alias.
409	`alias_reserved`	L’alias scelto è riservato al servizio. Scegli un altro alias.
409	`alias_taken`	L’alias è assegnato oppure riservato da una pubblicazione in corso. Scegli un altro alias oppure ricontrolla la disponibilità dopo la pubblicazione.
409	`already_member`	Questa affiliazione esiste già. Leggi le affiliazioni correnti prima di pubblicare un altro invito.
409	`already_retracted`	La dichiarazione indicata in `retracts` è già ritirata. Pubblica invece una dichiarazione nuova.
409	`api_key_limit`	Il titolare ha già 20 chiavi API non scadute e non revocate. Revoca una chiave inutilizzata prima di crearne un’altra. Le chiavi sospese vengono conteggiate.
409	`callback_used`	Questo accesso OAuth è già tornato una volta. Riprendi il flusso nel browser originale o avvia una nuova sessione di collegamento.
409	`erase_already_requested`	Una cancellazione è già in attesa. Leggi sulla scheda la data e ora di esecuzione prevista.
409	`erase_pending`	Su un registro in formato 2 la scheda ha una cancellazione in attesa. La sua chiusura firmata nomina la versione corrente, quindi la scheda non pubblica finché la cancellazione non è annullata. Annulla la cancellazione con POST /v1/identities/{n}/erase/cancel, poi pubblica la versione.
409	`grant_used`	Un grant di verifica o affiliazione è già stato usato. Controlla la versione risultante della scheda, poi ottieni un nuovo grant se serve ancora.
409	`identity_exists`	Un’identità usa già questo token. Controlla la pubblicazione esistente. Genera una nuova identità soltanto se serve una scheda diversa.
409	`invitation_closed`	L’invito è stato accettato, rifiutato o chiuso. Leggi le affiliazioni correnti prima di continuare.
409	`invitation_withdrawn`	L’organizzazione non offre più l’invito. Chiedi un nuovo invito.
409	`key_already_used`	Una chiave del dispositivo appartiene già a un’identità e non può essere riusata da un’altra. Usa la scheda esistente oppure genera una nuova chiave del dispositivo.
409	`no_erase_requested`	Non c’è una cancellazione in attesa da annullare. Leggi lo stato corrente della scheda.
409	`proof_pending`	L’accesso OAuth non è ancora tornato. Completa l’accesso al provider nel browser che lo ha avviato.
409	`replayed_nonce`	La chiave di firma ha già usato questo nonce. Controlla se la richiesta precedente è riuscita prima di crearne una nuova firmata.
409	`report_already_open`	Chi chiama ha già una segnalazione aperta per questa scheda. Attendi che lo staff risolva la segnalazione esistente.
409	`salt_ticket_invalid`	Il ticket del sale è sconosciuto, scaduto o già usato. Richiedi un nuovo ticket e ricostruisci e firma la prima versione con esso.
409	`signer_stale`	Su un registro in formato 2 `signer.n` di una voce firmata è indietro rispetto alla versione corrente della scheda che firma. Rileggi la scheda che firma e firma di nuovo la voce con la sua versione corrente in `signer.n`.
409	`takeover_already_open`	Un subentro per questo account collegato è già aperto. Leggi il subentro in attesa invece di aprirne un altro.
409	`takeover_closed`	Il subentro è già annullato o completato. Leggi il suo stato corrente.
409	`version_conflict`	La versione non può essere pubblicata rispetto allo stato corrente della scheda. Leggi la scheda più recente, riconcilia la modifica e firma una nuova versione.
410	`erased`	La scheda esisteva ed è stata cancellata o rimossa. La risposta contiene anche la ricevuta pubblica di cancellazione. Smetti di usare questa scheda come autorità corrente. Conserva soltanto la ricevuta pubblica se serve.
410	`proof_expired`	La sessione temporanea di prova dell’account è scaduta. Avvia una nuova sessione di collegamento.
413	`payload_too_large`	Il corpo della richiesta supera il limite in byte dell’endpoint. Riduci il corpo codificato. La gestione delle chiavi API ammette al massimo 8 KiB.
422	`account_not_linked`	L’avviso riguarda un account che la scheda non ha, oppure `to.subject` non è un altro account della scheda sulla stessa piattaforma. Indica un account collegato, oppure lascia `to.subject` null e scrivi il nuovo nome.
422	`authority_limit`	Su un registro in formato 2 la versione lascerebbe più di 1.024 membri nell’autorità di un’organizzazione: proprietari e amministratori, o ogni ruolo dello staff nell’organizzazione Veil. Togli prima un proprietario o un amministratore. Anche una rimozione nella stessa versione libera un posto.
422	`bad_entry`	Su un registro in formato 2 `salt`, `entry` o `closing` di una richiesta non vanno bene. `error.message` nomina il campo. Correggi il campo indicato, firma di nuovo la voce con la chiave della richiesta e manda una nuova richiesta firmata.
422	`cannot_revoke_self`	La revoca della propria chiave lascerebbe la scheda senza una chiave attiva, oppure la chiave di recupero viene revocata senza sostituirla. Mantieni un’altra chiave attiva. Sostituisci la chiave di recupero nella stessa versione che la revoca.
422	`closing_required`	Su un registro in formato 2 una cancellazione è arrivata senza la sua voce di chiusura firmata in `closing`. Firma la voce di chiusura con la stessa chiave e mandala come `closing`, con `text` e `signature`.
422	`external_limit`	La scheda terrebbe più di 16 chiavi pubbliche di altri sistemi, o un’operazione addExternalKey supera 16 KiB in JSON canonico. Togli prima una chiave. Anche una rimozione nella stessa versione libera un posto.
422	`file_needed`	Una firma staccata OpenPGP o una firma minisign legacy del file stesso. Copre i byte del file, e il server non vede mai il file. Controllala dove sta il file: su veil.rip/verify in un browser o con l’azione GitHub. Oppure firma un elenco di checksum, che il server controlla in ogni formato.
422	`grant_expired`	Il grant di verifica o affiliazione è scaduto. Ottieni un nuovo grant prima di pubblicare la versione.
422	`invalid_grant`	Il grant di verifica o affiliazione non è valido oppure appartiene a un’altra operazione. Usa il grant emesso per questa specifica scheda, account o affiliazione.
422	`invalid_logo`	L’immagine non supera i controlli su tipo, dimensione, risoluzione o contenuto. Dal 27 ottobre 2026 anche `inline` (il record porta l’immagine invece del suo hash), `missing` (un’immagine nuova senza `logoData`) o `mismatch` (`logoData` non ha la misura o lo SHA-256 che il record nomina). Correggi l’immagine secondo `error.message` prima di caricarla di nuovo.
422	`invalid_op`	Un’operazione è sconosciuta, malformata, non è del tipo o della versione della scheda, oppure non cambia niente. Correggi l’operazione indicata in `error.message`.
422	`invalid_record`	La versione dell’identità viola le regole del record firmato. Correggi il problema di convalida, rendi canonico il record e firmalo di nuovo.
422	`invalid_record_signature`	La firma della versione dell’identità non è valida. Firma il record canonico esatto con il prefisso identity-version e la chiave dichiarata.
422	`invalid_statement`	Un avviso o una dichiarazione di una scheda non rispetta lo schema: un campo mancante o in più, un testo troppo lungo o con caratteri nascosti, un link non https, una data nel futuro. Correggi il campo indicato in `error.message` e firma di nuovo la dichiarazione e la sua voce.
422	`invalid_statement_signature`	La firma della dichiarazione di cancellazione non è valida. Firma i byte esatti della dichiarazione con prefisso e chiave richiesti.
422	`key_expired`	La chiave OpenPGP o la sua sottochiave di firma è scaduta. Prolungane la scadenza sul tuo computer (gpg --quick-set-expire), poi incolla di nuovo la chiave e firma una sfida nuova.
422	`key_extra_packets`	La chiave OpenPGP porta ancora una foto, la certificazione di un’altra persona o altro materiale che la scheda non tiene. Aggiungi la chiave dalla pagina della tua scheda, che tiene solo quello che una scheda porta: la chiave, le sue sottochiavi di firma e gli user ID che scegli.
422	`key_revoked`	La chiave OpenPGP porta una firma di revoca. Una chiave revocata non va su una scheda. Porta una chiave che usi ancora.
422	`key_unsupported`	Un tipo di chiave che Veil non tiene: chiavi SSH su chiave di sicurezza (sk-…), ECDSA P-521, certificati SSH, una chiave OpenPGP che non è di versione 4, o un algoritmo OpenPGP diverso da RSA, ECDSA P-256 o P-384 ed Ed25519. Usa uno dei tipi elencati: ssh-ed25519, ssh-ecdsa-p256, ssh-ecdsa-p384, ssh-rsa, pgp, minisign, ed25519, ml-dsa-44, ml-dsa-65, ml-dsa-87.
422	`key_weak`	RSA sotto 2048 bit o DSA, in SSH o in OpenPGP, un punto Ed25519 di ordine piccolo, o una firma RSA fatta con SHA-1 (ssh-rsa). Porta una chiave più forte. ssh-keygen -Y sign firma RSA con rsa-sha2-512 per impostazione predefinita.
422	`keys_limit`	Su un registro in formato 2 la versione lascerebbe a una persona più di 64 chiavi attive. Revoca prima una chiave. Anche una revoca nella stessa versione libera un posto.
422	`label_mismatch`	prev, body, auth o state dell’intestazione non sono quelli che danno la catena, il corpo e le operazioni. Rileggi la scheda, pianifica le operazioni sul suo stato corrente e firma la nuova intestazione.
422	`last_owner`	La modifica lascerebbe un’organizzazione senza un proprietario accettato. Aggiungi o accetta un altro proprietario prima di rimuovere l’ultimo.
422	`links_need_verification`	Un nuovo collegamento di account non ha un grant di verifica accettabile. Completa la prova dell’account prima di pubblicarne il collegamento.
422	`members_limit`	Su un registro in formato 2 un invito porterebbe un’organizzazione oltre 100.000 membri e inviti in vigore. Togli dei membri o ritira degli inviti prima di invitare ancora.
422	`membership_needs_grant`	Un’affiliazione all’organizzazione non ha il grant di accettazione. Accetta l’invito e includi il grant nella prossima versione firmata.
422	`no_verified_email`	La scheda non ha un collegamento email verificato, quindi non c’è dove mandare gli avvisi. Collega prima un indirizzo email alla scheda, poi attiva gli avvisi.
422	`not_a_person`	La scheda è un’organizzazione dove è richiesta una persona. Usa l’endpoint delle organizzazioni oppure la scheda di una persona idonea.
422	`not_an_organization`	La scheda è una persona dove è richiesta un’organizzazione. Usa l’endpoint delle persone oppure la scheda di un’organizzazione.
422	`not_for_organizations`	Questo metodo prova un account personale e non è disponibile per le organizzazioni. Scegli un metodo di prova per organizzazioni supportato da /v1/platforms.
422	`private_key_material`	Un testo di un’operazione addExternalKey contiene materiale privato: una chiave privata PEM o OpenSSH, un blocco privato PGP o un pacchetto di chiave segreta, una chiave segreta minisign, una chiave segreta Ed25519 di 64 byte, o il seme o la chiave segreta di ML-DSA. Non si salva niente e la risposta non ripete il testo. Considera quella chiave esposta e sostituiscila. Manda solo la chiave pubblica e la firma della sfida.
422	`proof_anchor`	Il checkpoint citato non è di questo registro, non ha la firma del registro o il quorum delle controfirme, o la sua radice non è quella del registro a quella taglia. Cita intera la nota del checkpoint controfirmato come la scheda la dà in index.checkpoint.note.
422	`proof_failed`	Il provider, il codice o la prova pubblicata non hanno superato la verifica. Leggi `error.message`, correggi la prova e riprova mentre la sessione è valida.
422	`proof_invalid`	La sfida nomina un’altra chiave di dispositivo di quella che firma la versione, o la firma non è la firma della chiave sulla sfida di questa scheda. Il messaggio dice la causa: un’altra chiave, un altro namespace SSH, un hash che non vale, la sfida salvata in UTF-16 o con una riga vuota dopo, un altro testo, o una forma diversa da quella che dice proof.variant. Firma di nuovo i byte esatti della sfida dal browser che pubblica la versione: con namespace veil per SSH, con una firma staccata o in chiaro del file per OpenPGP. Una copia salvata su Windows (CRLF, un BOM UTF-8, senza l’ultimo a capo) vale se proof.variant ne dice la forma.
422	`proof_not_found`	Il record DNS, il file sul sito o il collegamento sul profilo richiesti non sono ancora visibili. Pubblica la prova esatta e attendi la propagazione prima di ricontrollare.
422	`proof_stale`	Il checkpoint citato dalla sfida è stato controfirmato più di 7 giorni fa, o l’ora dichiarata at è più vecchia di 7 giorni o avanti rispetto all’orologio del server. Prepara una sfida nuova dall’ultimo checkpoint della scheda e firmala di nuovo.
422	`self_target`	Una scheda non può segnalare se stessa. Scegli la scheda a cui si riferisce la segnalazione.
422	`staff_org_target`	Questa operazione non può riguardare l’organizzazione dello staff di Veil. Scegli un destinatario idoneo.
429	`alert_quota`	La scheda ha fatto 10 avvisi sugli account nelle ultime 24 ore. Aspetta i secondi indicati da `Retry-After`.
429	`rate_limited`	È stato superato un limite anonimo, delle richieste firmate o della chiave API. Attendi almeno i secondi indicati da `Retry-After`. Condividi coda e budget dei tentativi tra i tuoi processi.
429	`statement_quota`	La scheda ha pubblicato 10 dichiarazioni nelle ultime 24 ore, ritiri compresi. Aspetta i secondi indicati da `Retry-After`.
429	`too_many_attempts`	Questa sessione di prova ha superato il numero di tentativi con codice errato. Avvia una nuova sessione di prova. Questo codice è distinto da `rate_limited` per le quote.
500	`internal_error`	Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti. Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.
501	`format_not_implemented`	Sono supportate soltanto le risposte oEmbed in JSON. Richiedi format=json.
502	`log_mismatch`	La risposta del registro non corrisponde alla voce firmata o alla prova attese. Non considerare verificata la pubblicazione. Controlla scheda e registro prima di riprovare.
503	`busy`	L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database. Attendi i secondi indicati da `Retry-After` e riprova con attese crescenti e un limite.
503	`log_unavailable`	Al momento il registro pubblico non può essere letto, verificato o usato per pubblicare. Per le letture, considera il risultato non verificato e riprova più tardi. Prima di ripetere una scrittura, leggi la scheda per controllare se la pubblicazione è terminata.
503	`mail_unavailable`	Non è stato possibile inviare l’email di verifica. Riprova ad avviare la prova email tra qualche minuto.
503	`no_mail_transport`	Questo server non può mandare email. Non c’è niente da riprovare: il server non ha un trasporto di posta.
503	`provider_not_configured`	Il provider di prova scelto non è disponibile su questo server. Leggi /v1/platforms per i metodi disponibili.

Limiti ed errori
Mantieni le richieste limitate e segui la risposta quando una chiamata deve aspettare.
Usa una chiave API per sviluppatori
Dai a un’integrazione da server una quota condivisa senza concedere autorità sulla scheda Veil.
Invia una richiesta firmata
Usa la chiave di un dispositivo autorizzato per modificare schede e organizzazioni.
Verifica un messaggioPOST /v1/verify
Controlla un blocco firma oppure chiave, messaggio e firma espliciti. Questa POST legge soltanto.
Leggi una voce della documentazioneGET /v1/integrations/{id}
Leggi una guida o un contratto di endpoint con gli esempi.

Leggi questa voce in JSON