Errors

The API uses conventional HTTP status codes. A failed request returns a JSON body describing what went wrong.

Error response

401 Unauthorized


{
  "code": "401",
  "status": "UNAUTHORIZED",
  "message": "Access denied. Authorization required to access this resource.",
  "timestamp": "2026-01-31T09:30:00Z"
}

Status codes

Code	Meaning	What to do
200	OK. The request succeeded.	Read the response body.
400	Bad request. The body failed validation, the review request duplicates one you already sent, a Client Assist enquiry is already in a status that does not allow the action, or a webhook URL is already registered for that event.	Read the `errors` object, fix the request, and do not retry unchanged.
401	Unauthorized. The token is missing, invalid, or expired.	Check the `Authorization` header, then generate a new token.
403	Forbidden. Your token is valid, but the action is not allowed. For example, replying as a user outside your firm, calling the Client Assist API without an active Client Assist add-on, or using a token of a firm that is no longer on a premium membership.	Check the request against the endpoint’s errors table.
404	Not found. No review, review request, Client Assist enquiry or webhook with that identifier belongs to your firm.	Check the ID. Treat as a permanent failure.
5xx	Server error. Something went wrong on our side.	Retry with exponential backoff.

Every authentication failure comes back as 401, whether the token is missing, unrecognised, or past its expiry date. 403 is only returned for an action your token cannot perform, such as replying as a user outside your firm, or using the Client Assist API without Client Assist. Partner API tokens add a few errors of their own, for the X-Firm-Id header and for firms or actions that are not enabled on the token.

Validation errors

A review request whose reference already exists or is blocked returns an errors object keyed by field name:

400 Bad Request


{
  "errors": {
    "reference": "Review request with this reference already exists"
  }
}

A body that fails field validation, on any endpoint, returns a list instead, one entry per field:

400 Bad Request


[
  {
    "field": "reason",
    "error": ["A reason is required"]
  }
]

Handling errors

request.js


const response = await fetch(url, { headers })
 
if (!response.ok) {
  if (response.status === 401) {
    throw new Error('Access token is missing, expired, or invalid.')
  }
 
  if (response.status >= 500) {
    // Transient, safe to retry with backoff.
    throw new RetryableError(`Upstream error ${response.status}`)
  }
 
  throw new Error(`Request failed with ${response.status}`)
}
 
const data = await response.json()

Common causes

401 on every request. The header must read Authorization: Bearer {access_token}, with a single space after Bearer. Tokens are only read from that header, never a cookie.
401 after a period of working. The token reached the expiry you selected when you generated it. See Firm tokens.
400 on a review request. Check that firstName, lastName, email and reference are all present, that reference has not been used before, and that phoneNumber, if sent, is a valid UK mobile number.