Errors come in the API's usual envelope, {"error": {"code": "…", "message": "…"}}, with any extra data at the same level as error. The MCP server and the SDKs return the same codes; the CLI prints a message in Spanish and exits with the code in the last column.
| HTTP | Code | When | What to do | CLI exit |
|---|---|---|---|---|
| 412 | version_conflict | The zone is no longer at the version you sent in If-Match (or expected_version): someone changed it after your simulation. The body has current_version. Nothing was applied. | Look at what changed (zones diff), simulate again and confirm the new plan. | 3 |
| 428 | if_match_required | A revert was sent without If-Match. | Send the zone's current version. | 1 |
| 422 | reason_required | No reason, an empty one, more than 500 characters or a line break in it. | Send X-Change-Reason (--reason in the CLI, reason in MCP and the SDKs). | 2 or 1 |
| 422 | invalid | The change or the configuration it produces is not valid, or the configuration of an edge node could not be built with it. field names the field when there is one. | Fix the value; the simulation fails the same way, so check with a dry run. | 1 |
| 409 | missing_certs | A revert would leave sites without a valid certificate. The body has hostnames. | Revert anyway with allow_missing_certs (--allow-missing-certs), or issue the certificates first. | 1 |
| 403 | forbidden | Your role or scope does not allow the change, or a revert would restore groups of edge nodes (OpenWAF operators only) or another client (organisation-wide credentials only). | Use a credential with the right role, or revert to a version that does not need it. | 1 |
| 404 | not_found | The zone or version does not exist, or is outside your organisation or your token's scope. | Check the zone and the version number. | 1 |
| 502 | dns_out_of_sync | A delegated zone's DNS could not be published, and putting it back in line with the last committed configuration failed too. The change was rolled back. | Retry; if it persists, write to [email protected] with the zone. | 1 |
The CLI exits with 2 when it rejects the arguments itself, before calling the API (for example a missing --reason), and with 4 when --wait runs out of time before every edge node applied the change. See CLI exit codes.