Error Codes

Every error response from the Adatree APIs carries a machine-readable code in its errors[] array, alongside a human-readable title and detail:

{
  "errors": [
    {
      "code": "adatree.consent.inactive",
      "title": "Consent inactive",
      "detail": "Consent is no longer active"
    }
  ]
}

Drive your application logic from code, not from detail. The detail wording is for diagnostics and display, and may change at any time.

How codes are structured

A code has the form adatree.<category>.<condition>, for example adatree.consent.inactive. The category (the segment after adatree.) gives the default way to react, including to codes that are not listed below. New codes are introduced over time, so treat an unrecognised code according to its category rather than rejecting the response.

Category	Meaning	Default handling
consent	The state of the consent or arrangement.	Terminal: stop and inform the customer; retrying will not help.
request	Something about the request itself is wrong.	Terminal: fix the request before retrying.
auth	Authentication or authorisation of the caller.	Terminal: fix the credentials or scope.
dataholder	An interaction with the data holder failed.	Transient: retry later, with backoff.
platform	An error inside the Adatree platform.	Transient: retry later, with backoff.

“Terminal” means the request will not succeed if retried unchanged. “Transient” means it may succeed on a later attempt.

These are defaults, not absolutes

The handling above is the default for each category. Individual codes can override it. For example, adatree.dataholder.resource_not_found is terminal (retrying will not make the missing resource appear) even though dataholder errors are transient by default. Always check the specific code’s row below.

Codes

The codes below are those currently returned by the Consent and Data APIs. This list grows as other Adatree APIs adopt the taxonomy.

Code	Description
adatree.consent.inactive	The consent is no longer active (revoked, expired, or withdrawn).
adatree.consent.insufficient_scope	The consent arrangement does not grant the scope required for this request.
adatree.dataholder.upstream_error	The data holder returned an error while servicing the request.
adatree.dataholder.resource_not_found	Terminal (overrides the category default): the data holder does not have the requested resource, so retrying will not help.
adatree.dataholder.resource_unavailable	The data holder cannot serve the requested resource right now (temporarily unavailable); retry later with backoff.
adatree.dataholder.throttled	The data holder rate limited the request (HTTP 503 with a Retry-After header); retry after the indicated delay.
adatree.request.missing_field	A required field is missing from the request.
adatree.request.invalid_field	A field in the request has an invalid value.
adatree.request.missing_header	A required header is missing from the request.
adatree.request.invalid_header	A request header has an invalid value.
adatree.request.not_found	A referenced resource does not exist.
adatree.request.conflict	The resource was modified concurrently; reload it and try again.
adatree.auth.unauthorized	The access token is missing, expired, or invalid.
adatree.auth.forbidden	The access token does not grant the scope required for this operation.
adatree.platform.rate_limited	Too many requests to the Adatree platform; retry later with backoff.
adatree.platform.internal_error	An unexpected error occurred while processing the request.