Errors

When a request fails, the Diversity Sync API responds with a non-2xx HTTP status code and a JSON body containing a single nested error object that describes the problem. Check the status code first, then read the error object to debug.

Every response — success or failure — includes a Request-Id header, and the same value is echoed back as request_id inside the error object. Quote it when contacting support so we can trace the exact request you're asking about.

The error object

All /v1 errors share one shape: a top-level error object with a stable, machine-readable type and code, a human-readable message, an optional param, a doc_url pointing at this page, and the request_id of the failed request.

Branch on type and code in your integration — they are stable. The message is for humans and may change.

Attributes

Name
type
Type
string
Description
The high-level category of the error. One of invalid_request_error, authentication_error, permission_error, rate_limit_error, idempotency_error, or api_error.
Name
code
Type
string
Description
A specific, stable code identifying exactly what went wrong (for example parameter_invalid). See Error codes below.
Name
message
Type
string
Description
A human-readable description of the problem. For display and debugging only — never branch on this string.
Name
param
Type
string
Description
Present only when a single request parameter caused the error. Names the offending parameter (for example limit).
Name
doc_url
Type
string
Description
A link to the documentation for this code, of the form https://docs.diversitysync.com/errors#<code>.
Name
request_id
Type
string
Description
The identifier of the failed request, matching the Request-Id response header. Quote it to support.

A /v1 error (400 with param)

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "limit must be between 1 and 100.",
    "param": "limit",
    "doc_url": "https://docs.diversitysync.com/errors#parameter_invalid",
    "request_id": "req_8f2a1c9d4b"
  }
}

Authentication failures are deliberately uniform: a 401 always returns authentication_required and never reveals why the credential failed — whether it was missing, malformed, expired, or revoked. This prevents credential probing. Exchange your key for a fresh token and try again.

Status codes

The type of an error maps to its HTTP status. Use the status for transport-level handling (retry, back off) and the code for precise branching.

Name
200 / 204
Description
Success. 204 No Content is returned when there's nothing to return.
Name
400 Bad Request
Description
invalid_request_error — the request was malformed, missing a required parameter, or carried an invalid value.
Name
401 Unauthorized
Description
authentication_error — missing, expired, or revoked credentials. Always returns the uniform authentication_required code.
Name
403 Forbidden
Description
permission_error — authenticated, but the token's scopes don't grant access, or the organisation is locked.
Name
404 Not Found
Description
invalid_request_error — the resource doesn't exist within your organisation.
Name
409 Conflict
Description
invalid_request_error / idempotency_error — the request conflicts with the current state, or reuses an idempotency key.
Name
429 Too Many Requests
Description
rate_limit_error — you've exceeded the rate limit. Honour the Retry-After and RateLimit-* headers.
Name
500 / 502 / 503 Server Error
Description
api_error — something went wrong on our end. Retry, then contact support with the request_id if it persists.

Error codes

Every error carries a code. The list below documents each one; the heading anchor matches the doc_url returned in the error (for example parameter_invalid → #parameter_invalid).

invalid_request

The request was malformed in a way that isn't tied to a single parameter — for example a syntactically invalid body or an unsupported operation. Type: invalid_request_error (400).

parameter_invalid

A request parameter was present but its value was rejected — out of range, wrong type, or otherwise invalid. The offending parameter is named in param. Type: invalid_request_error (400).

parameter_missing

A required request parameter was omitted. The missing parameter is named in param. Type: invalid_request_error (400).

authentication_required

Authentication failed: the access token is missing, malformed, expired, or revoked. Uniform by design — it never reveals which. Type: authentication_error (401).

permission_denied

The token is valid but its scopes don't grant access to this resource or action. Type: permission_error (403).

org_locked

The organisation the key belongs to is locked (for example, suspended or pending billing action) and cannot be accessed. Type: permission_error (403).

resource_missing

The requested resource doesn't exist within your organisation. Type: invalid_request_error (404).

conflict

The request conflicts with the current state of the resource — for example a duplicate that violates a uniqueness constraint. Type: invalid_request_error (409).

idempotency_key_reused

An Idempotency-Key was reused with different request parameters than the original request that created it. Type: idempotency_error (409).

rate_limited

You've exceeded the rate limit for the endpoint. Back off and retry after the interval in the Retry-After and RateLimit-Reset headers. Type: rate_limit_error (429).

api_error

An unexpected error occurred on our end. These are transient — retry with back-off, and contact support with the request_id if it persists. Type: api_error (5xx).

The token endpoint

The token endpoint (POST /oauth/token) is not a /v1 resource and does not use the error object above. For 400, 401, and 429 responses it keeps the standard OAuth2 (RFC 6749) shape: a machine-readable error, a human-readable error_description, and a request_id for support.

Common error values are invalid_request (the request was malformed) and invalid_client (the key is invalid, expired, or revoked). When the token endpoint is rate limited it returns slow_down — wait for the Retry-After interval before retrying.

Token endpoint error (401)

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

Token endpoint rate limited (429)

{
  "error": "slow_down",
  "error_description": "Too many token requests from this IP. Retry after the interval in Retry-After.",
  "request_id": "req_aa01ff42d8"
}