Error Codes

When a request to the Paradym API fails, or when an issuance or verification session ends in a failure, Paradym returns a structured error that includes a numeric error code. These codes let you programmatically distinguish between the different kinds of errors that can occur.

All Paradym error codes are in the 2000 range. For example, 2002 corresponds to an AgentError.

Error structure

Errors returned by the API and included in webhook events follow the same structure:

{
  "message": "A human-readable description of what went wrong",
  "code": 2000,
  "details": [
    {
      "message": "An additional detail about the error"
    }
  ]
}

In API responses

When an API request fails, the error object is returned as the response body together with the relevant HTTP status code:

curl 'https://api.paradym.id/v1/projects' \
--header 'x-access-token: paradym_xxxxxxxx' \
--header 'Content-Type: application/json'

{
  "message": "Validation Failed",
  "code": 2000,
  "details": [
    {
      "message": "name is a required field",
      "field": "name"
    }
  ]
}

In webhook events

Failure events such as openid4vc.issuance.failed, openid4vc.verification.failed, didcomm.issuance.failed, and didcomm.verification.failed include the error in the error field of their payload. The same error is also available on the session when you retrieve it through the API.

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.issuance.failed",
  "payload": {
    "openId4VcIssuanceId": "<openid4vc-issuance-id>",
    "error": {
      "message": "An error occurred during credential issuance",
      "code": 2002,
      "details": []
    }
  }
}

Error code overview

The following table lists all Paradym error codes.