> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> HTTP status codes and error response format for the didx:me APIs.

## Error response format

All APIs follow the [JSON:API error format](https://jsonapi.org/format/#errors). Errors are returned as an array in the `errors` field:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Your access token is missing, expired, or invalid.

    **Fix:** Request a new access token from the [authentication endpoint](/products/didx-me/getting-started/authentication). Tokens expire after 300 seconds (5 minutes).

    ```json theme={null}
    {
      "errors": [
        {
          "status": "401",
          "code": "UNAUTHORIZED",
          "detail": "Access token is missing or expired"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="400 Bad Request">
    The request body contains invalid data. Check the `detail` and `source` fields to identify the issue.

    ```json theme={null}
    {
      "errors": [
        {
          "status": "400",
          "code": "VALIDATION_ERROR",
          "title": "Bad Request",
          "detail": "email must be a valid email address",
          "source": {
            "pointer": "/data/attributes/email"
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    {
      "errors": [
        {
          "status": "404",
          "code": "NOT_FOUND",
          "detail": "Credential template not found"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="409 Conflict">
    The resource you are trying to create already exists.

    ```json theme={null}
    {
      "errors": [
        {
          "status": "409",
          "code": "CONFLICT",
          "detail": "User with this email already exists"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    {
      "errors": [
        {
          "status": "500",
          "code": "INTERNAL_SERVER_ERROR",
          "detail": "An unexpected error occurred"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>