Aplicar un conjunto de reglas

Diferido Asíncrono · 202

POST /api/v1/servers/{vmid}/firewall/sets/{id}

operationIdpostServerFirewallSet

Nivel requerido: Explotación
Cuota: mutación, 300 llamadas por hora

Añade las reglas del conjunto a las del VPS y actualiza su cortafuegos. Diez conjuntos como máximo por VPS.

En un cortafuegos inactivo (enabled: false en GET /servers/{vmid}/firewall), como ocurre con el primer conjunto aplicado, las reglas se registran pero no filtran nada hasta que el cortafuegos se activa con PUT /servers/{vmid}/firewall y enabled: true. Espere a que termine la tarea devuelta antes de activarlo: una sincronización en curso hace que se responda 409 task_already_running.

Esta solicitud se procesa en segundo plano: responde de inmediato mientras el trabajo continúa. Sígala con los endpoints de tareas o solicitudes.

Parámetros de ruta

vmid string obligatorio: Identificador del VPS. Debe pertenecer a la cuenta y al alcance de la clave.

patrón ^\d+$ Ejemplo: 116807
id string obligatorio: Identificador del conjunto de reglas.

patrón ^\d+$ Ejemplo: 34

Respuestas

202

Solicitud aceptada y puesta en cola. Siga la tarea devuelta con GET /tasks/{id}.

La solicitud fue aceptada, no completada. La respuesta incluye una tarea que seguir.

{
  "data": {
    "tasks": [
      {
        "id": "tsk_000002e1",
        "status": "pending",
        "action": "firewall.sync",
        "vmid": "116807",
        "description": "Mise à jour des règles Firewall pour la VM : 116807",
        "created_at": "2026-08-20T14:31:02+02:00",
        "finished_at": null
      }
    ]
  }
}

Campos de la respuesta 9

data object
tasks object[]

Tareas creadas; siempre una matriz
id string

Identificador opaco

Ejemplo: tsk_000002e1
status string

unknown indicaría un estado que la API no sabe nombrar

uno de: pending, succeeded, failed, unknown
action string

Tipo de tarea

uno de: server.start, server.stop, server.shutdown, server.reboot, server.reset, server.rebuild, server.enable_rescue, server.disable_rescue, server.reboot_rescue, snapshot.create, snapshot.delete, snapshot.rollback, backup.create, backup.restore, iso.mount, iso.unmount, firewall.sync, firewall.unblock_port_25 TaskAction
vmid string
description string
created_at string (date-time)
finished_at string (date-time)

null mientras la tarea está en ejecución

401

Autenticación rechazada: invalid_token — encabezado Authorization ausente o mal formado, o clave desconocida; access_disabled — acceso a la API cortado para esta cuenta, o servicio de API cortado momentáneamente por LWS.

encabezado Authorization ausente o mal formado, o clave desconocida

{
  "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"
}

acceso a la API cortado para esta cuenta, o servicio de API cortado momentáneamente por 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"
}

Campos de la respuesta 18

type string (uri)

Ejemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obligatorio
title string

Título breve

Ejemplo: VPS introuvable

obligatorio
status integer (int64)

Estado HTTP

Ejemplo: 404

obligatorio
code string

Código de máquina estable (véase «Errores» en Primeros pasos)

Ejemplo: vm_not_found

obligatorio
detail string

Mensaje detallado

Ejemplo: Aucun VPS 999999 sur ce compte.

obligatorio
request_id string

Identificador de la petición, que debe facilitarse al soporte

Ejemplo: 3f9a1c07b2e45d18

obligatorio
errors object

validation_failed: mensaje por parámetro erróneo
required_level string

insufficient_scope: nivel exigido por la operación

uno de: read, exploitation, full
task_id string

task_already_running: tarea en curso en este VPS

Ejemplo: tsk_000002d5
family string

rate_limited: familia de cuota agotada

uno de: read, mutation, heavy
limit integer (int64)

rate_limited: límite por hora de la familia
retry_after integer (int64)

rate_limited: segundos de espera
lock string

server_locked: bloqueo establecido por el hipervisor (backup, snapshot, suspended…)

Ejemplo: snapshot
reason string

server_locked: operation_in_progress, hay una operación en curso, vuelva a intentarlo tras Retry-After; suspended, el VPS está en hibernación, arránquelo primero; support_notified, bloqueo anómalo, el equipo de LWS ha sido avisado y está interviniendo

uno de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: naturaleza de la intervención, inicio y fin previsto (null para una incidencia)
kind string

uno de: works, incident
started_at string (date-time)
expected_end string (date-time)

403

Acceso denegado: insufficient_scope — nivel de la clave insuficiente; ip_not_allowed — dirección de origen no autorizada.

nivel de la clave insuficiente

{
  "type": "https://docs.lws.fr/kvm/errors/insufficient-scope",
  "title": "Droits insuffisants",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Niveau de permission « exploitation » requis.",
  "request_id": "3f9a1c07b2e45d18",
  "required_level": "exploitation"
}

dirección de origen no autorizada

{
  "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"
}

Campos de la respuesta 18

type string (uri)

Ejemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obligatorio
title string

Título breve

Ejemplo: VPS introuvable

obligatorio
status integer (int64)

Estado HTTP

Ejemplo: 404

obligatorio
code string

Código de máquina estable (véase «Errores» en Primeros pasos)

Ejemplo: vm_not_found

obligatorio
detail string

Mensaje detallado

Ejemplo: Aucun VPS 999999 sur ce compte.

obligatorio
request_id string

Identificador de la petición, que debe facilitarse al soporte

Ejemplo: 3f9a1c07b2e45d18

obligatorio
errors object

validation_failed: mensaje por parámetro erróneo
required_level string

insufficient_scope: nivel exigido por la operación

uno de: read, exploitation, full
task_id string

task_already_running: tarea en curso en este VPS

Ejemplo: tsk_000002d5
family string

rate_limited: familia de cuota agotada

uno de: read, mutation, heavy
limit integer (int64)

rate_limited: límite por hora de la familia
retry_after integer (int64)

rate_limited: segundos de espera
lock string

server_locked: bloqueo establecido por el hipervisor (backup, snapshot, suspended…)

Ejemplo: snapshot
reason string

server_locked: operation_in_progress, hay una operación en curso, vuelva a intentarlo tras Retry-After; suspended, el VPS está en hibernación, arránquelo primero; support_notified, bloqueo anómalo, el equipo de LWS ha sido avisado y está interviniendo

uno de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: naturaleza de la intervención, inicio y fin previsto (null para una incidencia)
kind string

uno de: works, incident
started_at string (date-time)
expected_end string (date-time)

404

Recurso no encontrado: set_not_found — conjunto desconocido o perteneciente a otra cuenta; vm_not_found — VPS inexistente o fuera del alcance de la clave.

conjunto desconocido o perteneciente a otra cuenta

{
  "type": "https://docs.lws.fr/kvm/errors/set-not-found",
  "title": "Jeu de règles introuvable",
  "status": 404,
  "code": "set_not_found",
  "detail": "Jeu de règles introuvable.",
  "request_id": "3f9a1c07b2e45d18"
}

VPS inexistente o fuera del alcance de la clave

{
  "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"
}

Campos de la respuesta 18

type string (uri)

Ejemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obligatorio
title string

Título breve

Ejemplo: VPS introuvable

obligatorio
status integer (int64)

Estado HTTP

Ejemplo: 404

obligatorio
code string

Código de máquina estable (véase «Errores» en Primeros pasos)

Ejemplo: vm_not_found

obligatorio
detail string

Mensaje detallado

Ejemplo: Aucun VPS 999999 sur ce compte.

obligatorio
request_id string

Identificador de la petición, que debe facilitarse al soporte

Ejemplo: 3f9a1c07b2e45d18

obligatorio
errors object

validation_failed: mensaje por parámetro erróneo
required_level string

insufficient_scope: nivel exigido por la operación

uno de: read, exploitation, full
task_id string

task_already_running: tarea en curso en este VPS

Ejemplo: tsk_000002d5
family string

rate_limited: familia de cuota agotada

uno de: read, mutation, heavy
limit integer (int64)

rate_limited: límite por hora de la familia
retry_after integer (int64)

rate_limited: segundos de espera
lock string

server_locked: bloqueo establecido por el hipervisor (backup, snapshot, suspended…)

Ejemplo: snapshot
reason string

server_locked: operation_in_progress, hay una operación en curso, vuelva a intentarlo tras Retry-After; suspended, el VPS está en hibernación, arránquelo primero; support_notified, bloqueo anómalo, el equipo de LWS ha sido avisado y está interviniendo

uno de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: naturaleza de la intervención, inicio y fin previsto (null para una incidencia)
kind string

uno de: works, incident
started_at string (date-time)
expected_end string (date-time)

409

Conflicto con el estado actual: invalid_state — conjunto ya aplicado a este VPS; quota_exceeded — límite de 10 conjuntos aplicados alcanzado; task_already_running — ya hay una sincronización del cortafuegos o una reinstalación en curso; service_suspended — VPS desactivado o caducado: solo siguen siendo posibles las lecturas.

conjunto ya aplicado a este VPS

{
  "type": "https://docs.lws.fr/kvm/errors/invalid-state",
  "title": "Opération impossible en l'état",
  "status": 409,
  "code": "invalid_state",
  "detail": "Ce jeu de règles est déjà appliqué à ce VPS.",
  "request_id": "3f9a1c07b2e45d18"
}

límite de 10 conjuntos aplicados alcanzado

{
  "type": "https://docs.lws.fr/kvm/errors/quota-exceeded",
  "title": "Limite atteinte",
  "status": 409,
  "code": "quota_exceeded",
  "detail": "Ce VPS a atteint la limite de 10 jeux de règles appliqués.",
  "request_id": "3f9a1c07b2e45d18"
}

ya hay una sincronización del cortafuegos o una reinstalación en curso

{
  "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 synchronisation du pare-feu est déjà en cours sur ce VPS. Attendez qu'elle aboutisse.",
  "request_id": "3f9a1c07b2e45d18",
  "task_id": "tsk_000002d5"
}

VPS desactivado o caducado: solo siguen siendo posibles las lecturas

{
  "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"
}

Campos de la respuesta 18

type string (uri)

Ejemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obligatorio
title string

Título breve

Ejemplo: VPS introuvable

obligatorio
status integer (int64)

Estado HTTP

Ejemplo: 404

obligatorio
code string

Código de máquina estable (véase «Errores» en Primeros pasos)

Ejemplo: vm_not_found

obligatorio
detail string

Mensaje detallado

Ejemplo: Aucun VPS 999999 sur ce compte.

obligatorio
request_id string

Identificador de la petición, que debe facilitarse al soporte

Ejemplo: 3f9a1c07b2e45d18

obligatorio
errors object

validation_failed: mensaje por parámetro erróneo
required_level string

insufficient_scope: nivel exigido por la operación

uno de: read, exploitation, full
task_id string

task_already_running: tarea en curso en este VPS

Ejemplo: tsk_000002d5
family string

rate_limited: familia de cuota agotada

uno de: read, mutation, heavy
limit integer (int64)

rate_limited: límite por hora de la familia
retry_after integer (int64)

rate_limited: segundos de espera
lock string

server_locked: bloqueo establecido por el hipervisor (backup, snapshot, suspended…)

Ejemplo: snapshot
reason string

server_locked: operation_in_progress, hay una operación en curso, vuelva a intentarlo tras Retry-After; suspended, el VPS está en hibernación, arránquelo primero; support_notified, bloqueo anómalo, el equipo de LWS ha sido avisado y está interviniendo

uno de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: naturaleza de la intervención, inicio y fin previsto (null para una incidencia)
kind string

uno de: works, incident
started_at string (date-time)
expected_end string (date-time)

429

Cuota superada: rate_limited — cuota por hora de la familia agotada.

{
  "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 « mutation » : 300 appels par heure. Réessayez dans 95 seconde(s).",
  "request_id": "3f9a1c07b2e45d18",
  "family": "mutation",
  "limit": 300,
  "retry_after": 95
}

Campos de la respuesta 18

type string (uri)

Ejemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obligatorio
title string

Título breve

Ejemplo: VPS introuvable

obligatorio
status integer (int64)

Estado HTTP

Ejemplo: 404

obligatorio
code string

Código de máquina estable (véase «Errores» en Primeros pasos)

Ejemplo: vm_not_found

obligatorio
detail string

Mensaje detallado

Ejemplo: Aucun VPS 999999 sur ce compte.

obligatorio
request_id string

Identificador de la petición, que debe facilitarse al soporte

Ejemplo: 3f9a1c07b2e45d18

obligatorio
errors object

validation_failed: mensaje por parámetro erróneo
required_level string

insufficient_scope: nivel exigido por la operación

uno de: read, exploitation, full
task_id string

task_already_running: tarea en curso en este VPS

Ejemplo: tsk_000002d5
family string

rate_limited: familia de cuota agotada

uno de: read, mutation, heavy
limit integer (int64)

rate_limited: límite por hora de la familia
retry_after integer (int64)

rate_limited: segundos de espera
lock string

server_locked: bloqueo establecido por el hipervisor (backup, snapshot, suspended…)

Ejemplo: snapshot
reason string

server_locked: operation_in_progress, hay una operación en curso, vuelva a intentarlo tras Retry-After; suspended, el VPS está en hibernación, arránquelo primero; support_notified, bloqueo anómalo, el equipo de LWS ha sido avisado y está interviniendo

uno de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: naturaleza de la intervención, inicio y fin previsto (null para una incidencia)
kind string

uno de: works, incident
started_at string (date-time)
expected_end string (date-time)

502

Dependencia inaccesible: upstream_unavailable — error al aplicar el conjunto, o inventario de VPS momentáneamente no disponible.

{
  "type": "https://docs.lws.fr/kvm/errors/upstream-unavailable",
  "title": "Service momentanément indisponible",
  "status": 502,
  "code": "upstream_unavailable",
  "detail": "L'application du jeu de règles a échoué.",
  "request_id": "3f9a1c07b2e45d18"
}

Campos de la respuesta 18

type string (uri)

Ejemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obligatorio
title string

Título breve

Ejemplo: VPS introuvable

obligatorio
status integer (int64)

Estado HTTP

Ejemplo: 404

obligatorio
code string

Código de máquina estable (véase «Errores» en Primeros pasos)

Ejemplo: vm_not_found

obligatorio
detail string

Mensaje detallado

Ejemplo: Aucun VPS 999999 sur ce compte.

obligatorio
request_id string

Identificador de la petición, que debe facilitarse al soporte

Ejemplo: 3f9a1c07b2e45d18

obligatorio
errors object

validation_failed: mensaje por parámetro erróneo
required_level string

insufficient_scope: nivel exigido por la operación

uno de: read, exploitation, full
task_id string

task_already_running: tarea en curso en este VPS

Ejemplo: tsk_000002d5
family string

rate_limited: familia de cuota agotada

uno de: read, mutation, heavy
limit integer (int64)

rate_limited: límite por hora de la familia
retry_after integer (int64)

rate_limited: segundos de espera
lock string

server_locked: bloqueo establecido por el hipervisor (backup, snapshot, suspended…)

Ejemplo: snapshot
reason string

server_locked: operation_in_progress, hay una operación en curso, vuelva a intentarlo tras Retry-After; suspended, el VPS está en hibernación, arránquelo primero; support_notified, bloqueo anómalo, el equipo de LWS ha sido avisado y está interviniendo

uno de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: naturaleza de la intervención, inicio y fin previsto (null para una incidencia)
kind string

uno de: works, incident
started_at string (date-time)
expected_end string (date-time)

503

Servidor anfitrión en intervención: server_maintenance — servidor anfitrión en una intervención anunciada por LWS e inaccesible; respete 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"
  }
}

Campos de la respuesta 18

type string (uri)

Ejemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obligatorio
title string

Título breve

Ejemplo: VPS introuvable

obligatorio
status integer (int64)

Estado HTTP

Ejemplo: 404

obligatorio
code string

Código de máquina estable (véase «Errores» en Primeros pasos)

Ejemplo: vm_not_found

obligatorio
detail string

Mensaje detallado

Ejemplo: Aucun VPS 999999 sur ce compte.

obligatorio
request_id string

Identificador de la petición, que debe facilitarse al soporte

Ejemplo: 3f9a1c07b2e45d18

obligatorio
errors object

validation_failed: mensaje por parámetro erróneo
required_level string

insufficient_scope: nivel exigido por la operación

uno de: read, exploitation, full
task_id string

task_already_running: tarea en curso en este VPS

Ejemplo: tsk_000002d5
family string

rate_limited: familia de cuota agotada

uno de: read, mutation, heavy
limit integer (int64)

rate_limited: límite por hora de la familia
retry_after integer (int64)

rate_limited: segundos de espera
lock string

server_locked: bloqueo establecido por el hipervisor (backup, snapshot, suspended…)

Ejemplo: snapshot
reason string

server_locked: operation_in_progress, hay una operación en curso, vuelva a intentarlo tras Retry-After; suspended, el VPS está en hibernación, arránquelo primero; support_notified, bloqueo anómalo, el equipo de LWS ha sido avisado y está interviniendo

uno de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: naturaleza de la intervención, inicio y fin previsto (null para una incidencia)
kind string

uno de: works, incident
started_at string (date-time)
expected_end string (date-time)

Aplicar un conjunto de reglas

Parámetros de ruta

Respuestas

Informar de un error

Asistente IA