Error handling

Error response format

All APIs follow the JSON:API error format. Errors are returned as an array in the errors field:

{
  "errors": [
    {
      "id": "a1b2c3d4",
      "status": "400",
      "code": "VALIDATION_ERROR",
      "title": "Bad Request",
      "detail": "email must be a valid email address",
      "source": {
        "pointer": "/data/attributes/email"
      }
    }
  ]
}

Field	Description
`id`	Unique identifier for this error occurrence
`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 request field that caused the error
`source.parameter`	Query parameter that caused the error (if applicable)
`meta`	Additional metadata about the error (if applicable)

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

HTTP status codes

Status	Code	Description
Unauthorized	`401`	Authentication token is missing or expired. Request a new token
Bad Request	`400`	The request contains invalid or malformed parameters
Not Found	`404`	The requested resource (template, user, presentation, etc.) doesn’t exist
Conflict	`409`	The resource already exists (e.g. duplicate user)
Internal Server Error	`500`	An unexpected error occurred on the server. Retry after a short delay; contact support if it persists

Common errors

401 Unauthorized

Your access token is missing, expired, or invalid.Fix: Request a new access token from the authentication endpoint. Tokens expire after 300 seconds (5 minutes).

{
  "errors": [
    {
      "status": "401",
      "code": "UNAUTHORIZED",
      "detail": "Access token is missing or expired"
    }
  ]
}

400 Bad Request

The request body contains invalid data. Check the detail and source fields to identify the issue.

{
  "errors": [
    {
      "status": "400",
      "code": "VALIDATION_ERROR",
      "title": "Bad Request",
      "detail": "email must be a valid email address",
      "source": {
        "pointer": "/data/attributes/email"
      }
    }
  ]
}

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"
    }
  ]
}

500 Internal Server Error

An unexpected error occurred on the server. This is not caused by your request. Retry after a short delay; if the issue persists, contact support.

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

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

Error response format

HTTP status codes

Common errors

​Error response format

​HTTP status codes

​Common errors

Error response format

HTTP status codes

Common errors