Skip to content
Adatree

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.

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.

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 Transient (overrides the category default): the request conflicts with the resource’s current state, so it cannot be served now; retry once the conflicting state clears.
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.