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.request.conflict (HTTP 409) is safe to retry once after reloading the resource, even though request errors are terminal by default. Always check the specific code’s row below.

Codes

The codes below are those currently returned by the Consent API. 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.not_found	No consent matches the supplied arrangement identifier.
adatree.dataholder.upstream_error	The data holder returned an error while servicing the request.
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.internal_error	An unexpected error occurred while processing the request.