Error handling

Every API error, an answer with a status of 400 or more, is thrown (TypeScript) or raised (Python) as OpenWAFError:

The codes are the API's; the ones specific to versioned writes are listed in Change control errors.

#Version conflicts

A write sent with an expected version that is no longer current fails with status 412 and code version_conflict, and applies nothing. body.current_version is the zone's version now. Simulate again, review the new plan and confirm with the new version; do not retry blindly.

import { OpenWAFError } from "./openwaf.ts";

try {
  await owf.createRecord({ zone: zoneId, body: record }, { reason, ifMatch: plan.from_version! });
} catch (err) {
  if (err instanceof OpenWAFError && err.code === "version_conflict") {
    const { current_version } = err.body as { current_version: number };
    console.log(`zone is now at version ${current_version}: simulate again`);
  } else {
    throw err;
  }
}

from openwaf import OpenWAFError

try:
    owf.create_record(zone=zone_id, body=record, reason=reason, if_match=plan["from_version"])
except OpenWAFError as e:
    if e.code == "version_conflict":
        print("zone is now at version %d: simulate again" % e.body["current_version"])
    else:
        raise

#Validation errors

invalid (status 422) means the API rejected a value; field names it when it can, such as content or records[0].ttl. A simulation fails the same way as the real write, so a dry run is a safe way to validate input.

#Client-side failures

#Retries

The SDKs do not retry. Reads and simulations are safe to retry after a network error or a 5xx. A write sent with ifMatch is safe too: if the first attempt was applied, the retry fails with version_conflict instead of applying the change twice.