Reinstallare un VPS
Differito Asincrono · 202
POST
/api/v1/
operationIdpostServerRebuild
- Livello richiesto
- Completo
- Quota
- operazioni pesanti, 6 chiamate all'ora per VPS (60 per account)
Reinstalla il sistema. Tutto il contenuto del disco viene distrutto (file, configurazione, account), senza possibilità di ritorno: ciò che non si trova in un backup o in uno snapshot va perso.
La coppia os / variant va ripresa così com'è da GET /catalog/os-templates. La memoria del VPS viene confrontata con il minimo del template prima di qualsiasi azione: una reinstallazione che lascerebbe la macchina incapace di avviarsi viene rifiutata con 409.
Le password vengono generate, non scelte, e restituite una sola volta in questa risposta: sempre root_password, più app_password per una variante applicativa (variant diverso da default). Diventano effettive all'avvio del sistema reinstallato.
ssh_key_ids sostituisce le chiavi da installare sulla macchina ricostruita. Un identificativo che non appartiene all'account non installa nulla. Una chiave weak viene rifiutata (400), prima di qualsiasi azione.
Questa richiesta viene elaborata in background: risponde immediatamente mentre il lavoro continua. Seguila con gli endpoint di task o request.
Parametri del percorso
-
vmidstring obbligatorio -
Identificativo del VPS. Deve appartenere all'account e rientrare nell'ambito della chiave.
Corpo della richiesta
application/json
-
osstringobbligatorioCampo
osdi una voce diGET /catalog/os-templates -
variantstringfacoltativoCampo
variantdella stessa voce -
ssh_key_idsstring[]facoltativoChiavi dell'account da installare. Se assente o vuoto, questa chiamata non modifica le chiavi.
Esempio di richiesta
{
"os": "debian-12",
"variant": "default",
"ssh_key_ids": [
"45"
]
}
Risposte
202
Reinstallazione messa in coda; password restituite una sola volta
La richiesta è stata accettata, non completata. La risposta contiene un task da seguire.
{
"data": {
"tasks": [
{
"id": "tsk_000002e1",
"status": "pending",
"action": "server.rebuild",
"vmid": "116807",
"description": "Réinstallation du serveur VPS-116807 avec le template Debian 12",
"created_at": "2026-08-20T14:31:02+02:00",
"finished_at": null
}
],
"root_password": "shfKvbnERTUP2345",
"effective_after_reboot": true
}
}
Campi della risposta 12
-
dataobject -
tasksobject[] -
idstringIdentificativo opaco
-
statusstringunknownsegnalerebbe uno stato che l'API non sa denominare -
actionstringTipo di task
-
vmidstring -
descriptionstring -
created_atstring (date-time) -
finished_atstring (date-time)nullfinché il task è in esecuzione -
root_passwordstringPassword root generata, restituita una sola volta
-
app_passwordstringPassword applicativa, per una variante diversa da
default -
effective_after_rebootboolean
400
Parametri non validi: validation_failed — os assente, oppure coppia os / variant sconosciuta al catalogo; validation_failed — chiave di ssh_key_ids contrassegnata come weak.
validation_failed — os assente, oppure coppia os / variant sconosciuta al catalogo; validation_failed — chiave di ssh_key_ids contrassegnata come weak.os assente, oppure coppia os / variant sconosciuta al catalogo
{
"type": "https://docs.lws.fr/kvm/errors/validation-failed",
"title": "Paramètres invalides",
"status": 400,
"code": "validation_failed",
"detail": "Aucun système ne correspond à ce couple os / variant.",
"request_id": "3f9a1c07b2e45d18",
"errors": {
"os": "Reprenez un couple os / variant de /catalog/os-templates."
}
}
chiave di ssh_key_ids contrassegnata come weak
{
"type": "https://docs.lws.fr/kvm/errors/validation-failed",
"title": "Paramètres invalides",
"status": 400,
"code": "validation_failed",
"detail": "La clé SSH 45 ne respecte plus les critères actuels (type reconnu, RSA d'au moins 2048 bits) : elle ne peut pas être posée à la réinstallation.",
"request_id": "3f9a1c07b2e45d18",
"errors": {
"ssh_key_ids": "Retirez la clé 45, ou remplacez-la par une clé conforme."
}
}
Campi della risposta 18
-
typestring (uri)obbligatorio -
titlestringobbligatorioTitolo breve
-
statusinteger (int64)obbligatorioStato HTTP
-
codestringobbligatorioCodice macchina stabile (vedere «Errori» in Per iniziare)
-
detailstringobbligatorioMessaggio dettagliato
-
request_idstringobbligatorioIdentificativo della richiesta, da comunicare al supporto
-
errorsobjectvalidation_failed: messaggio per ogni parametro errato -
required_levelstringinsufficient_scope: livello richiesto dall'operazione -
task_idstringtask_already_running: task in corso su questo VPS -
familystringrate_limited: famiglia di quota esaurita -
limitinteger (int64)rate_limited: limite orario della famiglia -
retry_afterinteger (int64)rate_limited: secondi da attendere -
lockstringserver_locked: blocco impostato dall'hypervisor (backup,snapshot,suspended…) -
reasonstringserver_locked:operation_in_progress, è in corso un'operazione, riprovi dopoRetry-After;suspended, il VPS è in ibernazione, lo avvii prima;support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo -
maintenanceobjectserver_maintenance: natura dell'intervento, inizio e fine prevista (nullper un incidente) -
kindstring -
started_atstring (date-time) -
expected_endstring (date-time)
401
Autenticazione rifiutata: invalid_token — intestazione Authorization assente o non valida, oppure chiave sconosciuta; access_disabled — accesso API disattivato per questo account, oppure servizio API momentaneamente sospeso da LWS.
invalid_token — intestazione Authorization assente o non valida, oppure chiave sconosciuta; access_disabled — accesso API disattivato per questo account, oppure servizio API momentaneamente sospeso da LWS.intestazione Authorization assente o non valida, oppure chiave sconosciuta
{
"type": "https://docs.lws.fr/kvm/errors/invalid-token",
"title": "Authentification invalide",
"status": 401,
"code": "invalid_token",
"detail": "Clé inconnue ou révoquée.",
"request_id": "3f9a1c07b2e45d18"
}
accesso API disattivato per questo account, oppure servizio API momentaneamente sospeso da LWS
{
"type": "https://docs.lws.fr/kvm/errors/access-disabled",
"title": "Accès API désactivé",
"status": 401,
"code": "access_disabled",
"detail": "L'accès API est désactivé pour ce compte. Réactivez-le depuis la page « API / MCP » du panel.",
"request_id": "3f9a1c07b2e45d18"
}
Campi della risposta 18
-
typestring (uri)obbligatorio -
titlestringobbligatorioTitolo breve
-
statusinteger (int64)obbligatorioStato HTTP
-
codestringobbligatorioCodice macchina stabile (vedere «Errori» in Per iniziare)
-
detailstringobbligatorioMessaggio dettagliato
-
request_idstringobbligatorioIdentificativo della richiesta, da comunicare al supporto
-
errorsobjectvalidation_failed: messaggio per ogni parametro errato -
required_levelstringinsufficient_scope: livello richiesto dall'operazione -
task_idstringtask_already_running: task in corso su questo VPS -
familystringrate_limited: famiglia di quota esaurita -
limitinteger (int64)rate_limited: limite orario della famiglia -
retry_afterinteger (int64)rate_limited: secondi da attendere -
lockstringserver_locked: blocco impostato dall'hypervisor (backup,snapshot,suspended…) -
reasonstringserver_locked:operation_in_progress, è in corso un'operazione, riprovi dopoRetry-After;suspended, il VPS è in ibernazione, lo avvii prima;support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo -
maintenanceobjectserver_maintenance: natura dell'intervento, inizio e fine prevista (nullper un incidente) -
kindstring -
started_atstring (date-time) -
expected_endstring (date-time)
403
Accesso negato: insufficient_scope — livello della chiave insufficiente; ip_not_allowed — indirizzo di chiamata non autorizzato.
insufficient_scope — livello della chiave insufficiente; ip_not_allowed — indirizzo di chiamata non autorizzato.livello della chiave insufficiente
{
"type": "https://docs.lws.fr/kvm/errors/insufficient-scope",
"title": "Droits insuffisants",
"status": 403,
"code": "insufficient_scope",
"detail": "Niveau de permission « full » requis.",
"request_id": "3f9a1c07b2e45d18",
"required_level": "full"
}
indirizzo di chiamata non autorizzato
{
"type": "https://docs.lws.fr/kvm/errors/ip-not-allowed",
"title": "Adresse non autorisée",
"status": 403,
"code": "ip_not_allowed",
"detail": "L'adresse 203.0.113.10 ne figure pas parmi les adresses autorisées de ce compte.",
"request_id": "3f9a1c07b2e45d18"
}
Campi della risposta 18
-
typestring (uri)obbligatorio -
titlestringobbligatorioTitolo breve
-
statusinteger (int64)obbligatorioStato HTTP
-
codestringobbligatorioCodice macchina stabile (vedere «Errori» in Per iniziare)
-
detailstringobbligatorioMessaggio dettagliato
-
request_idstringobbligatorioIdentificativo della richiesta, da comunicare al supporto
-
errorsobjectvalidation_failed: messaggio per ogni parametro errato -
required_levelstringinsufficient_scope: livello richiesto dall'operazione -
task_idstringtask_already_running: task in corso su questo VPS -
familystringrate_limited: famiglia di quota esaurita -
limitinteger (int64)rate_limited: limite orario della famiglia -
retry_afterinteger (int64)rate_limited: secondi da attendere -
lockstringserver_locked: blocco impostato dall'hypervisor (backup,snapshot,suspended…) -
reasonstringserver_locked:operation_in_progress, è in corso un'operazione, riprovi dopoRetry-After;suspended, il VPS è in ibernazione, lo avvii prima;support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo -
maintenanceobjectserver_maintenance: natura dell'intervento, inizio e fine prevista (nullper un incidente) -
kindstring -
started_atstring (date-time) -
expected_endstring (date-time)
404
Risorsa non trovata: vm_not_found — VPS inesistente o fuori dall'ambito della chiave.
vm_not_found — VPS inesistente o fuori dall'ambito della chiave.{
"type": "https://docs.lws.fr/kvm/errors/vm-not-found",
"title": "VPS introuvable",
"status": 404,
"code": "vm_not_found",
"detail": "Aucun VPS 999999 sur ce compte.",
"request_id": "3f9a1c07b2e45d18"
}
Campi della risposta 18
-
typestring (uri)obbligatorio -
titlestringobbligatorioTitolo breve
-
statusinteger (int64)obbligatorioStato HTTP
-
codestringobbligatorioCodice macchina stabile (vedere «Errori» in Per iniziare)
-
detailstringobbligatorioMessaggio dettagliato
-
request_idstringobbligatorioIdentificativo della richiesta, da comunicare al supporto
-
errorsobjectvalidation_failed: messaggio per ogni parametro errato -
required_levelstringinsufficient_scope: livello richiesto dall'operazione -
task_idstringtask_already_running: task in corso su questo VPS -
familystringrate_limited: famiglia di quota esaurita -
limitinteger (int64)rate_limited: limite orario della famiglia -
retry_afterinteger (int64)rate_limited: secondi da attendere -
lockstringserver_locked: blocco impostato dall'hypervisor (backup,snapshot,suspended…) -
reasonstringserver_locked:operation_in_progress, è in corso un'operazione, riprovi dopoRetry-After;suspended, il VPS è in ibernazione, lo avvii prima;support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo -
maintenanceobjectserver_maintenance: natura dell'intervento, inizio e fine prevista (nullper un incidente) -
kindstring -
started_atstring (date-time) -
expected_endstring (date-time)
409
Conflitto con lo stato attuale: invalid_state — memoria del VPS inferiore al minimo del sistema, oppure VPS assente dal database del suo hypervisor; task_already_running — una reinstallazione è già in corso; service_suspended — VPS disattivato o scaduto: sono possibili solo le letture; server_locked — VPS bloccato dall'hypervisor, vedere reason; con operation_in_progress, Retry-After indica l'attesa consigliata.
invalid_state — memoria del VPS inferiore al minimo del sistema, oppure VPS assente dal database del suo hypervisor; task_already_running — una reinstallazione è già in corso; service_suspended — VPS disattivato o scaduto: sono possibili solo le letture; server_locked — VPS bloccato dall'hypervisor, vedere reason; con operation_in_progress, Retry-After indica l'attesa consigliata.memoria del VPS inferiore al minimo del sistema, oppure VPS assente dal database del suo hypervisor
{
"type": "https://docs.lws.fr/kvm/errors/invalid-state",
"title": "Opération impossible en l'état",
"status": 409,
"code": "invalid_state",
"detail": "Ce système demande au moins 7 Go de mémoire ; ce VPS en dispose de 4.",
"request_id": "3f9a1c07b2e45d18"
}
una reinstallazione è già in corso
{
"type": "https://docs.lws.fr/kvm/errors/task-already-running",
"title": "Opération déjà en cours",
"status": 409,
"code": "task_already_running",
"detail": "Une réinstallation est déjà en cours sur ce VPS. Attendez qu'elle aboutisse.",
"request_id": "3f9a1c07b2e45d18",
"task_id": "tsk_000002d5"
}
VPS disattivato o scaduto: sono possibili solo le letture
{
"type": "https://docs.lws.fr/kvm/errors/service-suspended",
"title": "Service suspendu",
"status": 409,
"code": "service_suspended",
"detail": "Le VPS 116807 est expiré.",
"request_id": "3f9a1c07b2e45d18"
}
VPS bloccato dall'hypervisor, vedere reason; con operation_in_progress, Retry-After indica l'attesa consigliata
{
"type": "https://docs.lws.fr/kvm/errors/server-locked",
"title": "Serveur verrouillé",
"status": 409,
"code": "server_locked",
"detail": "Action impossible pour le moment : une sauvegarde est en cours sur le serveur. Réessayez dans quelques minutes.",
"request_id": "3f9a1c07b2e45d18",
"lock": "snapshot",
"reason": "operation_in_progress"
}
Campi della risposta 18
-
typestring (uri)obbligatorio -
titlestringobbligatorioTitolo breve
-
statusinteger (int64)obbligatorioStato HTTP
-
codestringobbligatorioCodice macchina stabile (vedere «Errori» in Per iniziare)
-
detailstringobbligatorioMessaggio dettagliato
-
request_idstringobbligatorioIdentificativo della richiesta, da comunicare al supporto
-
errorsobjectvalidation_failed: messaggio per ogni parametro errato -
required_levelstringinsufficient_scope: livello richiesto dall'operazione -
task_idstringtask_already_running: task in corso su questo VPS -
familystringrate_limited: famiglia di quota esaurita -
limitinteger (int64)rate_limited: limite orario della famiglia -
retry_afterinteger (int64)rate_limited: secondi da attendere -
lockstringserver_locked: blocco impostato dall'hypervisor (backup,snapshot,suspended…) -
reasonstringserver_locked:operation_in_progress, è in corso un'operazione, riprovi dopoRetry-After;suspended, il VPS è in ibernazione, lo avvii prima;support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo -
maintenanceobjectserver_maintenance: natura dell'intervento, inizio e fine prevista (nullper un incidente) -
kindstring -
started_atstring (date-time) -
expected_endstring (date-time)
429
Quota superata: rate_limited — quota oraria della famiglia esaurita.
rate_limited — quota oraria della famiglia esaurita.{
"type": "https://docs.lws.fr/kvm/errors/rate-limited",
"title": "Quota dépassé",
"status": 429,
"code": "rate_limited",
"detail": "Quota dépassé pour les opérations de type « heavy » sur le VPS 116807 : 6 appels par heure. Réessayez dans 214 seconde(s).",
"request_id": "3f9a1c07b2e45d18",
"family": "heavy",
"limit": 6,
"retry_after": 214
}
Campi della risposta 18
-
typestring (uri)obbligatorio -
titlestringobbligatorioTitolo breve
-
statusinteger (int64)obbligatorioStato HTTP
-
codestringobbligatorioCodice macchina stabile (vedere «Errori» in Per iniziare)
-
detailstringobbligatorioMessaggio dettagliato
-
request_idstringobbligatorioIdentificativo della richiesta, da comunicare al supporto
-
errorsobjectvalidation_failed: messaggio per ogni parametro errato -
required_levelstringinsufficient_scope: livello richiesto dall'operazione -
task_idstringtask_already_running: task in corso su questo VPS -
familystringrate_limited: famiglia di quota esaurita -
limitinteger (int64)rate_limited: limite orario della famiglia -
retry_afterinteger (int64)rate_limited: secondi da attendere -
lockstringserver_locked: blocco impostato dall'hypervisor (backup,snapshot,suspended…) -
reasonstringserver_locked:operation_in_progress, è in corso un'operazione, riprovi dopoRetry-After;suspended, il VPS è in ibernazione, lo avvii prima;support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo -
maintenanceobjectserver_maintenance: natura dell'intervento, inizio e fine prevista (nullper un incidente) -
kindstring -
started_atstring (date-time) -
expected_endstring (date-time)
502
Dipendenza irraggiungibile: hypervisor_unreachable; upstream_unavailable — catalogo, chiavi SSH o coda di reinstallazione non disponibili.
hypervisor_unreachable; upstream_unavailable — catalogo, chiavi SSH o coda di reinstallazione non disponibili.Hypervisor irraggiungibile
{
"type": "https://docs.lws.fr/kvm/errors/hypervisor-unreachable",
"title": "Hyperviseur injoignable",
"status": 502,
"code": "hypervisor_unreachable",
"detail": "L'hyperviseur hébergeant ce VPS n'a pas répondu. Réessayez dans quelques instants.",
"request_id": "3f9a1c07b2e45d18"
}
catalogo, chiavi SSH o coda di reinstallazione non disponibili
{
"type": "https://docs.lws.fr/kvm/errors/upstream-unavailable",
"title": "Service momentanément indisponible",
"status": 502,
"code": "upstream_unavailable",
"detail": "La demande de réinstallation n'a pas pu être enregistrée. Réessayez dans quelques instants.",
"request_id": "3f9a1c07b2e45d18"
}
Campi della risposta 18
-
typestring (uri)obbligatorio -
titlestringobbligatorioTitolo breve
-
statusinteger (int64)obbligatorioStato HTTP
-
codestringobbligatorioCodice macchina stabile (vedere «Errori» in Per iniziare)
-
detailstringobbligatorioMessaggio dettagliato
-
request_idstringobbligatorioIdentificativo della richiesta, da comunicare al supporto
-
errorsobjectvalidation_failed: messaggio per ogni parametro errato -
required_levelstringinsufficient_scope: livello richiesto dall'operazione -
task_idstringtask_already_running: task in corso su questo VPS -
familystringrate_limited: famiglia di quota esaurita -
limitinteger (int64)rate_limited: limite orario della famiglia -
retry_afterinteger (int64)rate_limited: secondi da attendere -
lockstringserver_locked: blocco impostato dall'hypervisor (backup,snapshot,suspended…) -
reasonstringserver_locked:operation_in_progress, è in corso un'operazione, riprovi dopoRetry-After;suspended, il VPS è in ibernazione, lo avvii prima;support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo -
maintenanceobjectserver_maintenance: natura dell'intervento, inizio e fine prevista (nullper un incidente) -
kindstring -
started_atstring (date-time) -
expected_endstring (date-time)
503
Server host in intervento: server_maintenance — server host in intervento annunciato da LWS e irraggiungibile; rispetti Retry-After.
server_maintenance — server host in intervento annunciato da LWS e irraggiungibile; rispetti Retry-After.{
"type": "https://docs.lws.fr/kvm/errors/server-maintenance",
"title": "Intervention en cours sur le serveur hôte",
"status": 503,
"code": "server_maintenance",
"detail": "Le serveur hébergeant ce VPS fait l'objet d'une intervention programmée par LWS : il est momentanément inaccessible. Fin prévue : 2026-10-21T18:00:00+02:00.",
"request_id": "3f9a1c07b2e45d18",
"maintenance": {
"kind": "works",
"started_at": "2026-10-21T14:00:00+02:00",
"expected_end": "2026-10-21T18:00:00+02:00"
}
}
Campi della risposta 18
-
typestring (uri)obbligatorio -
titlestringobbligatorioTitolo breve
-
statusinteger (int64)obbligatorioStato HTTP
-
codestringobbligatorioCodice macchina stabile (vedere «Errori» in Per iniziare)
-
detailstringobbligatorioMessaggio dettagliato
-
request_idstringobbligatorioIdentificativo della richiesta, da comunicare al supporto
-
errorsobjectvalidation_failed: messaggio per ogni parametro errato -
required_levelstringinsufficient_scope: livello richiesto dall'operazione -
task_idstringtask_already_running: task in corso su questo VPS -
familystringrate_limited: famiglia di quota esaurita -
limitinteger (int64)rate_limited: limite orario della famiglia -
retry_afterinteger (int64)rate_limited: secondi da attendere -
lockstringserver_locked: blocco impostato dall'hypervisor (backup,snapshot,suspended…) -
reasonstringserver_locked:operation_in_progress, è in corso un'operazione, riprovi dopoRetry-After;suspended, il VPS è in ibernazione, lo avvii prima;support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo -
maintenanceobjectserver_maintenance: natura dell'intervento, inizio e fine prevista (nullper un incidente) -
kindstring -
started_atstring (date-time) -
expected_endstring (date-time)