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

# Troubleshooting

> Learn how to handle errors and troubleshoot issues with the Knowledge Graph GraphQL API, including rate limiting, server errors, query complexity issues, and authentication problems.

export const GatedCallout = ({children}) => <div className="eyebrow-callout not-prose rounded-xl border border-gray-200/80 p-5 dark:border-white/10" style={{
  marginBottom: "1rem",
  borderRadius: "4px"
}}>
    <div className="mb-3">
      <Badge color="orange" size="md" icon="lock">
        Gated
      </Badge>
    </div>
    <div className="callout-body text-[15px] leading-relaxed text-gray-700 dark:text-gray-300">{children}</div>
    <style>{`.callout-body a { text-decoration: underline; text-decoration-color: #178251; }`}</style>
  </div>;

export const EarlyAccessCallout = ({children}) => <div className="eyebrow-callout not-prose rounded-xl border border-gray-200/80 p-5 dark:border-white/10" style={{
  marginBottom: "1rem",
  borderRadius: "4px"
}}>
    <div className="mb-3">
      <Badge color="green" size="md" icon="flask">
        Early access
      </Badge>
    </div>
    <div className="callout-body text-[15px] leading-relaxed text-gray-700 dark:text-gray-300">{children}</div>
    <style>{`.callout-body a { text-decoration: underline; text-decoration-color: #178251; }`}</style>
  </div>;

<GatedCallout>
  Access to this resource is restricted and requires prior approval. In some cases, a license may also be required. Contact [support@learningcommons.org ↗](mailto:support@learningcommons.org) for information about access and eligibility.
</GatedCallout>

## Query too complex

If your query times out or fails:

* Reduce the depth of nested relationships
* Implement pagination on nested connections
* Split complex queries into multiple simpler ones

## No results returned

* Check filter conditions are correct
* Verify field names match the schema
* Use introspection queries to explore available fields

## Authentication errors

* Ensure your API key is valid and active
* Check that the x-api-key header is properly set

## Rate limiting

The API implements rate limiting to ensure fair usage. Please reach out to [support@learningcommons.org](mailto:support@learningcommons.org) ↗ for requests regarding rate limit adjustments.

* HTTP 429: Too Many Requests
* Rate limit: 2 requests per second with burst capacity up to 10 requests
* Implement exponential backoff when receiving rate limit errors

## Server errors

* HTTP 502/504: Server errors may occur with large queries
* Reduce page size and retry when encountering server errors
* Maximum recommended page size: 1000 items

## Payload and timeout limits

The API has the following technical limitations:

* **Request timeout:** 30 seconds maximum
* **Request payload size:** 10 MB maximum
* **Response payload size:** 6 MB maximum
* **Query complexity:** Deep nested queries may hit processing limits

**Best practices to avoid limits:**

* Use pagination for large result sets
* Limit field selection to only required data
* Avoid deeply nested queries (>5 levels)
* Consider breaking complex queries or add filtering like grade level or subject.

## GraphQL errors

GraphQL errors are returned in the response body:

```text theme={null}
{
  "errors": [
    {
      "message": "Field 'invalidField' doesn't exist on type 'Lesson'",
      "locations": [{"line": 2, "column": 5}]
    }
  ]
}
```