# Errores

> Códigos de error de las escrituras versionadas, las simulaciones y las vueltas atrás, con su estado HTTP, el código de salida de la CLI y qué hacer.

Los errores llegan en el sobre habitual de la API, `{"error": {"code": "…", "message": "…"}}`, con los datos adicionales al mismo nivel que `error`. El servidor MCP y los SDK devuelven los mismos códigos; la CLI imprime un mensaje en español y sale con el código de la última columna.

| HTTP | Código | Cuándo | Qué hacer | Salida de la CLI |
|---|---|---|---|---|
| 412 | `version_conflict` | La zona ya no está en la versión que enviaste en `If-Match` (o `expected_version`): alguien la cambió después de tu simulación. El cuerpo lleva `current_version`. No se ha aplicado nada. | Mira qué ha cambiado (`zones diff`), vuelve a simular y confirma el plan nuevo. | 3 |
| 428 | `if_match_required` | Se ha pedido una vuelta atrás sin `If-Match`. | Envía la versión actual de la zona. | 1 |
| 422 | `reason_required` | Falta el motivo, está vacío, pasa de 500 caracteres o lleva un salto de línea. | Envía `X-Change-Reason` (`--reason` en la CLI, `reason` en MCP y en los SDK). | 2 o 1 |
| 422 | `invalid` | El cambio, o la configuración que produce, no es válido, o con él no se puede construir la configuración de algún nodo de borde. `field` indica el campo cuando lo hay. | Corrige el valor; la simulación falla igual, así que compruébalo con una simulación. | 1 |
| 409 | `missing_certs` | Volver atrás dejaría sitios sin certificado válido. El cuerpo lleva `hostnames`. | Vuelve atrás igualmente con `allow_missing_certs` (`--allow-missing-certs`), o emite antes los certificados. | 1 |
| 403 | `forbidden` | Tu rol o tu ámbito no permiten el cambio, o la vuelta atrás restauraría grupos de nodos de borde (solo operadores de OpenWAF) u otro cliente (solo credenciales de toda la organización). | Usa una credencial con el rol adecuado, o vuelve a una versión que no lo necesite. | 1 |
| 404 | `not_found` | La zona o la versión no existen, o están fuera de tu organización o del ámbito de tu token. | Revisa la zona y el número de versión. | 1 |
| 502 | `dns_out_of_sync` | No se ha podido publicar el DNS de una zona delegada y tampoco se ha podido volver a dejarlo como la última configuración confirmada. El cambio se ha deshecho. | Reintenta; si sigue pasando, escribe a support@openwaf.dev con la zona. | 1 |

La CLI sale con 2 cuando rechaza ella misma los argumentos, antes de llamar a la API (por ejemplo, si falta `--reason`), y con 4 cuando `--wait` agota el plazo antes de que todos los nodos de borde apliquen el cambio. Ver [Códigos de salida de la CLI](https://developers.openwaf.dev/es/cli/output-and-exit-codes/#exit-codes).