Errors

When something goes wrong, the Diversity Sync API responds with a non-2xx HTTP status code and a JSON body describing the problem. Check the status code first, then use the body to debug.

Error responses never include staff, participant, or organisation data beyond what's needed to describe the problem, and are always scoped to the organisation the key belongs to.

Status codes

Name
200 / 204
Description
Success. 204 No Content is returned when there's nothing to return.
Name
400 Bad Request
Description
The request was malformed — for example an out-of-range query parameter.
Name
401 Unauthorized
Description
Missing, expired, or revoked credentials. Exchange your key for a fresh token.
Name
403 Forbidden
Description
Authenticated, but the token's scopes don't grant access to this resource.
Name
404 Not Found
Description
The resource doesn't exist within your organisation.
Name
500 Server Error
Description
Something went wrong on our end. Retry, then contact support if it persists.

Error shapes

Resource endpoints (everything under /v1) return an error with a machine-readable error name and a human-readable message. Some errors also include a details object with a structured code.

The token endpoint (/oauth/token) uses the OAuth2 error shape instead: an error of invalid_request (the request was malformed) or invalid_client (the key is invalid, expired, or revoked), with a human-readable error_description.

Resource error (e.g. 403)

{
  "error": "Forbidden",
  "message": "Resource requires permission 'View staff profiles'"
}

Token endpoint error (401)

{
  "error": "invalid_client",
  "error_description": "Invalid, expired, or revoked API key"
}