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 [email protected] 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.