Error handling

Two layers of errors

Requests pass through an API gateway before they reach a service. The two layers fail differently, and only the service layer returns JSON.

The gateway enforces authentication. It rejects a missing, malformed, or wrong-audience token and answers in plain text, not JSON:API. A client that parses every error body as JSON will throw on the most common failure there is.

Gateway errors (plain text)

Status	Body	Cause
`403`	`RBAC: access denied`	No `Authorization` header, or the path isn’t permitted for your token.
`401`	`Jwt header is an invalid JSON`	The bearer token is malformed.
`403`	`Audiences in Jwt are not allowed`	The token is valid but was issued for a different audience or client.

A missing token yields 403, not 401. Check the response Content-Type before parsing, because gateway errors are text/plain.

Service error format

Once a request reaches a service, errors follow the JSON:API error format, returned as an array in the errors field:

{
  "errors": [
    {
      "id": "a1b2c3d4-6619-433c-ab26-c0f25fae3bd4",
      "status": "400",
      "code": "VALIDATION_ERROR",
      "title": "Bad Request",
      "detail": "Invalid email address",
      "source": {
        "pointer": "/email"
      }
    }
  ]
}

Field	Description
`id`	Unique identifier for this error occurrence. Quote it when contacting support.
`status`	HTTP status code as a string
`code`	Machine-readable error code
`title`	Short, human-readable summary of the error
`detail`	Specific explanation of what went wrong
`source.pointer`	JSON pointer to the offending request field, for example `/issuerDisplay/displayName`
`source.parameter`	Query parameter that caused the error (if applicable)
`meta`	Additional metadata (if applicable). Carries `issues[]` on some services. See below.

Only detail is guaranteed to be present. All other fields are optional.

The pointer is relative to the request body root (/email), not the JSON:API document root (/data/attributes/email).

Validation errors vary by service

Two different shapes are in use. Handle both. me-creds and me-wallet emit one error object per failed field, with code: "VALIDATION_ERROR" and a source.pointer. That is the shape above. consumer-onboarding and tenant provisioning emit a single BAD_REQUEST with the field paths under meta.issues:

{
  "errors": [
    {
      "id": "f89d3c0d-e325-4f67-b508-52eb4e721ca7",
      "status": "400",
      "code": "BAD_REQUEST",
      "title": "Bad Request",
      "detail": "Request validation failed",
      "meta": {
        "issues": [
          {
            "code": "too_small",
            "minimum": 1,
            "path": ["issuerDisplay", "displayName"],
            "message": "Too small: expected string to have >=1 characters"
          }
        ]
      }
    }
  ]
}

HTTP status codes

Status	Code	Description
Bad Request	`400`	The request contains invalid or malformed parameters
Unauthorized	`401`	The token is malformed. Rejected at the gateway, plain text
Forbidden	`403`	No token supplied, or the token isn’t permitted for this path. Rejected at the gateway, plain text
Not Found	`404`	The requested resource (preset, template, user, presentation) doesn’t exist
Conflict	`409`	The resource already exists, or claims an identifier another resource already holds
Gone	`410`	The presentation request has expired and can no longer be answered
Unprocessable Entity	`422`	Understood but unsatisfiable, for example when no held credential matches the request
Internal Server Error	`500`	An unexpected error occurred on the server. Retry after a short delay; contact support if it persists
Service Unavailable	`503`	A dependency was unreachable. Retry with backoff

Error codes

Code	Status	Meaning
`VALIDATION_ERROR`	`400`	A request field failed validation. See `source.pointer`
`BAD_REQUEST`	`400`	Malformed request. Field paths may appear under `meta.issues`
`UNAUTHORIZED`	`401`	Token missing or rejected at the service layer
`FORBIDDEN`	`403`	Authenticated, but not allowed to perform this action
`NOT_FOUND`	`404`	Resource does not exist
`CONFLICT`	`409`	Resource already exists, or its identifier is taken
`PRESENTATION_REQUEST_EXPIRED`	`410`	The presentation request passed its `expiresAt`
`PRESENTATION_REQUEST_UNSATISFIABLE`	`422`	The holder has no credential that satisfies the request
`UNPROCESSABLE_ENTITY`	`422`	The request is well-formed but violates a data-integrity constraint
`INTERNAL_SERVER_ERROR`	`500`	Unexpected server-side failure
`SERVICE_UNAVAILABLE`	`503`	A dependency was unreachable

Not every service emits every code. The PRESENTATION_REQUEST_* codes come from the wallet API, and only some services emit FORBIDDEN, UNPROCESSABLE_ENTITY, and SERVICE_UNAVAILABLE.

Common errors

403 and 401: token missing, malformed, or expired

This is the most common failure. The gateway rejects it, so the body is plain text:

RBAC: access denied

A missing Authorization header gives 403, not 401. A malformed token gives 401 Jwt header is an invalid JSON. A token for the wrong client gives 403 Audiences in Jwt are not allowed.Fix. Request a new access token from the authentication endpoint. Tokens expire after 300 seconds (five minutes).The wallet API returns the service-layer form instead:

{
  "errors": [
    {
      "id": "37feefc3-0b9e-4c2b-bea1-f8c35796c24f",
      "status": "401",
      "code": "UNAUTHORIZED",
      "title": "Unauthorized",
      "detail": "The request was missing access token."
    }
  ]
}

400 Bad Request

The request body contains invalid data. Check source.pointer, or meta.issues[].path depending on the service, to identify the field.

{
  "errors": [
    {
      "id": "a1b2c3d4-6619-433c-ab26-c0f25fae3bd4",
      "status": "400",
      "code": "VALIDATION_ERROR",
      "title": "Bad Request",
      "detail": "Invalid email address",
      "source": {
        "pointer": "/email"
      }
    }
  ]
}

On me-creds and me-wallet, the service returns one error object per failed field, so a request with three bad fields returns three entries in errors. On consumer-onboarding and tenant provisioning you get a single BAD_REQUEST object and the per-field detail sits in meta.issues[]. Read both. Iterate errors[] and, for each entry, check source.pointer first, falling back to meta.issues[].path.

404 Not Found

The resource you referenced doesn’t exist. This typically means a template ID, user ID, or presentation ID is incorrect or has been deleted.

{
  "errors": [
    {
      "status": "404",
      "code": "NOT_FOUND",
      "detail": "Credential template not found"
    }
  ]
}

409 Conflict

The resource you are trying to create already exists.

{
  "errors": [
    {
      "status": "409",
      "code": "CONFLICT",
      "detail": "User with this email already exists"
    }
  ]
}

410 Gone: presentation request expired

The holder tried to answer a presentation request past its expiresAt. Requests expire 15 minutes after creation, so generate them at the moment you’re ready to show them rather than in advance.Fix. Create a new presentation request and deliver it again. You cannot revive the expired one.

{
  "errors": [
    {
      "status": "410",
      "code": "PRESENTATION_REQUEST_EXPIRED",
      "title": "Presentation Request Expired",
      "detail": "Presentation request has expired"
    }
  ]
}

422 Unprocessable Entity: request unsatisfiable

The holder has no credential that satisfies the request. Either they don’t hold the credential type you asked for, or the credentials they hold don’t come from an issuer you accept.Fix. This is not a client bug. Check the preset’s trusted issuers against what the holder has.

{
  "errors": [
    {
      "status": "422",
      "code": "PRESENTATION_REQUEST_UNSATISFIABLE",
      "title": "Presentation Request Unsatisfiable",
      "detail": "No credentials satisfy the presentation request"
    }
  ]
}

500 Internal Server Error

An unexpected error occurred on the server. Your request did not cause it. Retry after a short delay, and contact support if the problem persists.

{
  "errors": [
    {
      "status": "500",
      "code": "INTERNAL_SERVER_ERROR",
      "detail": "An unexpected error occurred"
    }
  ]
}

Overview

User Onboarding

Issuance

Verification

Branding

Webhooks

Custom Templates (advanced)

Errors

Two layers of errors

Gateway errors (plain text)

Service error format

Validation errors vary by service

HTTP status codes

Error codes

Common errors

​Two layers of errors

​Gateway errors (plain text)

​Service error format

​Validation errors vary by service

​HTTP status codes

​Error codes

​Common errors

Two layers of errors

Gateway errors (plain text)

Service error format

Validation errors vary by service

HTTP status codes

Error codes

Common errors