# Troubleshooting

This document outlines the steps an Admin User should follow to triage and resolve background issues. Currently this feature is only supported for Jira and Alation integration issues.

{% hint style="warning" %}
Only Admin users can access this feature
{% endhint %}

***

### Health Check (UI Method)

A quick way to check the current status of the integrations.

1. Navigate to Telmai UI with Admin user, and specify your tenant.
2. On the top right menu, click the warnings icon.
3. This will list any open issues if existing

### Deeper Diagnosis (API Method)

For issues that aren't immediately clear from the UI or for checking deeper job details, use the Telmai API.

* Method: `GET`
* URL: `{config_endpoint}/{tenant}/errors`
* Authentication: Requires a valid Admin user token.

#### Query Parameters

| Parameter | Type    | Description                                                                                | Required | Default |
| --------- | ------- | ------------------------------------------------------------------------------------------ | -------- | ------- |
| `limit`   | Integer | Maximum number of error records to return. Used for pagination and managing response size. | False    | 100     |

***

#### Response

* Status Code: `200 OK`
* Body: A JSON array of error objects, ordered by `timestamp` in descending order (most recent first).

**Response Body Schema**

The response is a list of objects, each representing a single background error event:

```json
[
  {
    "timestamp": "2025-10-28T14:01:00.000Z",
    "error_class": "INTEGRATION_JIRA", 
    "message": "Some error...",
    "exception_type": "RuntimeException",
    "stack_trace": "additional multiline info...."
  },
  // ... more error objects
]
```

**Field Definitions**

| Field            | Description                                                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp`      | The exact time the error occurred.                                                                                                                  |
| `error_class`    | Categorization of the error source. Possible values: `INTEGRATION_JIRA` (ticket creation/updates), `INTEGRATION_ALATION` (catalog synchronization). |
| `message`        | A concise, human-readable summary of the error.                                                                                                     |
| `exception_type` | The underlying programmatic exception type.                                                                                                         |
| `stack_trace`    | Detailed technical information, including the call sequence.                                                                                        |

***

#### 📝 Example Usage

This example retrieves the 5 most recent errors from the `prod_tenant`.

**Request**

```http
GET /my-telmai-backend/prod_tenant/errors?limit=5
```

**Response (Abbreviated)**

```json
[
  {
    "timestamp": "2025-10-28T14:05:30.000Z",
    "error_class": "INTEGRATION_ALATION",
    "message": "Alation API returned 401: Invalid API token or insufficient permissions.",
    "exception_type": "UnauthorizedException",
    "stack_trace": "..."
  },
  {
    "timestamp": "2025-10-28T14:01:00.000Z",
    "error_class": "INTEGRATION_JIRA",
    "message": "Failed to create issue: Field 'priority' is required.",
    "exception_type": "JiraServiceException",
    "stack_trace": "..."
  }
]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.telm.ai/telmai/admin-apis/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.