Errors and status codes on the public API

Q: Can I rely on the error code strings?

Yes. The code field is stable and intended for branching in your integration. The message is human-facing and may be reworded, so do not match on it.

Every public-API response uses standard HTTP status codes and a consistent error envelope. A read returns 200, a successful enquiry returns 201, malformed JSON returns 400, an unknown key returns 404, a validation failure returns 422, and a rate-limit overflow returns 429. Errors always carry a machine-readable code and a human message so you can branch on the code and log the message.

The status codes you will see

Code	Meaning	Typical cause
`200`	OK	A successful read (loyalty tiers, CMS page, billers, MCP).
`201`	Created	An enquiry was recorded.
`400`	Bad Request	Malformed JSON or a structurally invalid body.
`404`	Not Found	An unknown CMS key, or an unpublished page.
`422`	Unprocessable Entity	A well-formed request that fails validation — missing consent, oversized fields, bad email.
`429`	Too Many Requests	The per-IP window was exceeded; retry after `Retry-After`.

The error envelope

Every non-2xx response carries the same shape: a top-level error object with a stable code and a human-readable message.

{
  "error": {
    "code": "validation_failed",
    "message": "fields.consent must be \"yes\"."
  }
}

Branch on code in your integration — it is stable and safe to switch on. Surface message to a developer or a log, not usually to an end user.

Handling each code

400/422 — fix the request; do not retry unchanged. 404 — the resource does not exist or is unpublished; handle as empty. 429 — honour Retry-After and retry. 5xx — a transient server error; retry with capped exponential back-off. A plain 200 or 201 means you are done.

Frequently asked questions

What is the difference between 400 and 422?

A 400 means the request was malformed — bad JSON, wrong structure. A 422 means the request parsed fine but failed a business rule, like a missing consent flag or an oversized payload. Fix a 400 by correcting the syntax; fix a 422 by correcting the values.

Should I retry a 422?

No. A 422 is deterministic — the same request will fail the same way. Correct the input first. Only 429 and transient 5xx responses should be retried.

Can I rely on the error code strings?

Yes. The code field is stable and intended for branching in your integration. The message is human-facing and may be reworded, so do not match on it.

Errors and status codes on the public API

The status codes you will see

The error envelope

Handling each code

Frequently asked questions

Funding for UK limited companies