# Troubleshooting

https://api-docs.lumar.io/docs/graphql/troubleshooting

This page covers common issues encountered when working with the Lumar GraphQL API and how to diagnose them.

## 401 Unauthorized

**Symptom:** Every request returns HTTP 401 or an `UNAUTHENTICATED` error.

**Diagnosis:** Verify your authentication is working by running a simple `me` query:

```graphql
query CheckMyPermissions {
  me {
    id
    username
    accounts(first: 5) {
      nodes {
        id
        name
      }
    }
  }
}
```

**Response:**
```json
{
  "data": {
    "me": {
      "id": "TjAwNFVzZXI4NjE",
      "username": "your.username@example.com",
      "accounts": {
        "nodes": [
          {
            "id": "TjAwN0FjY291bnQ3MTU",
            "name": "Your Account Name"
          }
        ]
      }
    }
  }
}
```

**Common causes:**

- The `x-auth-token` header is missing or misspelt.
- The session token has expired. Re-authenticate using `createSessionUsingUserKey`.
- The user key or service account key has been revoked.

## Empty results

**Symptom:** A query returns an empty `nodes` array when you expect data.

**Common causes:**

- The crawl has not finished yet. Check the crawl status:

```graphql
query VerifyCrawlStatus($crawlId: ObjectID!) {
  getCrawl(id: $crawlId) {
    id
    status
    createdAt
    finishedAt
    crawlUrlsTotal
    crawlLevels
  }
}
```

**Variables:**
```json
{
  "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ"
}
```

**Response:**
```json
{
  "data": {
    "getCrawl": {
      "id": "TjAwNUNyYXdsMTU4MzI0NQ",
      "status": "Finished",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "finishedAt": "2025-01-15T10:30:00.000Z",
      "crawlUrlsTotal": 2186,
      "crawlLevels": 5
    }
  }
}
```

- You are querying a report template that has no matching URLs for this crawl.
- A filter is too restrictive. Remove filters temporarily to confirm data exists, then add them back incrementally.
- You are querying the wrong account or project. Verify the ID using the `me` query above.

## Rate limit errors (429)

**Symptom:** Requests fail with HTTP 429 `Too Many Requests`.

**Solution:**

- Reduce request frequency to stay under the 6000 requests / 5-minute limit.
- Implement exponential backoff (see [Error Handling](error-handling)).
- Combine multiple small queries into a single larger query where possible.

## Crawl stuck in Queued or Crawling status

**Symptom:** A crawl never reaches `Finished` status.

**Common causes:**

- The site is very large and the crawl is still in progress. Use the crawl status query above to check `crawlUrlsTotal` for progress.
- The crawl hit an error and moved to an error state. Check the `status` field -- if it shows `Paused` or an unexpected state, the crawl may need attention.
- Rate limiting on the target site is slowing the crawl. Check your project's crawl rate settings.

## Missing webhook notifications

**Symptom:** Webhooks are configured but no notifications are received.

**Checklist:**

1. Verify the webhook exists on the test suite (query the `webhooks` or `slackWebhooks` connection on the test suite).
2. Confirm the `alertTypes` include the relevant alert level (e.g., `Fail`).
3. Check that the webhook URL is accessible from the internet and returns a 2xx response.
4. For Slack webhooks, verify the incoming webhook URL is still active in your Slack workspace settings.
5. Ensure a build has actually completed -- webhooks fire only when a build finishes.

## Query validation errors

**Symptom:** The API returns a 400 status with syntax or validation errors.

**Common causes:**

- A required variable is missing. Check the query signature for required (`!`) parameters.
- An enum value is incorrect (e.g., using `"Finished"` as a string instead of the enum `Finished`).
- The query references a field that does not exist on the type. Use the [schema explorer](/docs/schema.md) to verify field names.

## Timeout or slow responses

**Symptom:** Requests take a very long time or time out.

**Solutions:**

- Reduce the `first` parameter to fetch fewer records per page.
- Remove deeply nested relationship fields that trigger additional data loading.
- Avoid requesting `totalCount` on very large connections if you do not need it.
- Use report downloads for bulk data export instead of paginating through the API (see [Generate Report Downloads](generate-report-downloads)).