Errors

The error format of the OpenWAF API, its HTTP statuses and every stable error code with its meaning.

Errors answer an HTTP status and a JSON body:

{
  "error": {
    "code": "version_conflict",
    "message": "the configuration changed: the current version is 13"
  },
  "current_version": 13
}

Field	Meaning
`error.code`	Stable code: use it in your code.
`error.message`	Human explanation; its wording may change.
`error.field`	Field that failed validation, when there is one (e.g. `ttl`, `records[3].content`).

Some codes add fields next to error: current_version (version_conflict), hostnames (missing_certs), plan (merge_not_equivalent).

HTTP statuses

Status	Meaning
`200`, `201`	Success. With `dry_run=1`, `200` carries the plan of the change.
`204`	Success without a body.
`400`	Malformed request: invalid JSON, unknown field, invalid query parameter.
`401`	Missing, invalid, expired or revoked token.
`403`	The token's role or limits do not allow the operation.
`404`	The resource does not exist or the token cannot see it.
`409`	The current state does not allow the change.
`412`	`If-Match` does not match the current version.
`413`	The body is too large.
`422`	Validation error or missing change reason.
`428`	The operation requires `If-Match`.
`429`	Too many requests: wait the seconds in `Retry-After`.
`502`, `503`	A dependency did not answer or the feature is not available: retry later.

Error codes

Code	Status	Description
`bad_request`	`400`	Malformed request: invalid JSON, unknown field or invalid parameter.
`unauthorized`	`401`	Missing, invalid, expired or revoked token.
`forbidden`	`403`	The role or the limits of the token do not allow the operation.
`token_scope`	`403`	A cache-purge-only token called another route.
`feature_disabled`	`403`	The feature (egress) is not enabled for the organization.
`zone_limit`	`403`	The organization has reached its zone limit.
`org_suspended`	`403`	The organization is suspended; writes are refused.
`org_pending_approval`	`403`	The organization is waiting for approval; writes are refused.
`not_found`	`404`	The resource does not exist or the token cannot see it.
`host_not_in_zone`	`404`	The name is neither the zone nor below it.
`conflict`	`409`	The current state does not allow the change (e.g. a disabled zone, the last owner, a duplicate name).
`zone_exists`	`409`	The domain is already added.
`zone_overlaps`	`409`	The domain is a parent or a subdomain of a zone of another organization or another client.
`zone_not_active`	`409`	The zone is not active.
`zone_not_external`	`409`	The operation is only for external zones.
`zone_merged`	`409`	The zone is merged into another one and is read-only until it is unmerged.
`merge_not_equivalent`	`409`	The merge would change how some name is served; the body carries the plan.
`merge_not_reversible`	`409`	The zone is not merged or its parent changed since the merge.
`missing_certs`	`409`	Some sites would be left without a valid certificate; the body lists the hostnames.
`already_member`	`409`	The person is already a member of the organization.
`owner_of_zones`	`409`	The change would leave zones without an owner.
`client_has_zones`	`409`	The client still has zones; move or delete them first.
`host_taken`	`409`	The name is used by another organization.
`target_in_use`	`409`	An egress agent still allows the target.
`version_conflict`	`412`	`If-Match` does not match the current version; the body carries `current_version`.
`too_large`	`413`	The body or the file is too large.
`invalid`	`422`	Validation error; `field` names the field.
`reason_required`	`422`	The `X-Change-Reason` header is missing or invalid.
`if_match_required`	`428`	The operation requires `If-Match`.
`rate_limited`	`429`	Too many requests; wait the seconds in `Retry-After`.
`too_many_streams`	`429`	Too many event streams open in the organization.
`dns_backend`	`502`	The DNS service rejected the change; retry later.
`dns_unavailable`	`502`	The public DNS did not answer.
`credential_store`	`502`	The credential store refused the write; retry later.
`unavailable`	`503`	The feature is not available right now; retry later.
`busy`	`503`	Too many checks in progress; retry in a few seconds.
`internal`	`500`	Unexpected error; retry, and contact [email protected] if it persists.

Errors

#HTTP statuses

#Error codes

HTTP statuses

Error codes