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

# Rate limits

> How Pylon limits API traffic, how to tell when a request was limited, and how to retry and pace your requests

A request over your organization's rate limit is rejected before it does anything. Retry it after the number of seconds in the `Retry-After` header.

## How limits work

Each limit has two numbers: a **sustained rate** and a **burst**.

* **Sustained rate.** The steady number of requests you can send per minute. Allowance refills continuously, not at the top of each minute: a limit of N per minute gives you one more request every 60 ÷ N seconds.
* **Burst.** How many requests can arrive at once when you haven't used any allowance. After a burst, the allowance refills at the sustained rate, one request at a time.

Limits are counted **per organization**, separately for each kind of operation. Pricing requests have their own allowance, so a burst of pricing calls doesn't use up the allowance for loan updates, and the other way round. All API keys in an organization share the same allowance.

Limits count requests as they **arrive**, not how many are in progress. Ten requests that each take a second use the same allowance as ten that each take ten seconds.

## Finding and raising your organization's limits

To find out your organization's limits, or to raise them for an integration that sends many requests, such as batch pricing, contact Pylon support. You can also read the current sustained rate for any call from the `X-RateLimit-Limit` header on its response.

### Pricing limits

Pricing operations (scenario pricing, loan product pricing, optimal structure, marketing rates and prequalification) have a lower limit than the rest of the API. Most other calls are unlikely to reach theirs.

A GraphQL request that asks for several pricing fields at once counts once for each field.

## Recognizing a limited request

How a limited request looks depends on the API you call.

### GraphQL

A limited GraphQL request returns **HTTP 200**, like every GraphQL response. The limited field comes back as `null` with an error whose `extensions.code` is `RATE_LIMITED`:

```json theme={null}
{
  "errors": [
    {
      "message": "Rate limit exceeded",
      "path": ["scenario", "pricing"],
      "extensions": {
        "code": "RATE_LIMITED",
        "errorId": "errx_YE1XkY8y6bffrkLHgBBhnc"
      }
    }
  ],
  "data": { "scenario": null }
}
```

Check `extensions.code`, not the HTTP status or the message text.

### REST

A limited REST request returns **HTTP 429** with `"code": "RATE_LIMITED"` in the body. See [MISMO import](https://docs.pylon.mortgage/guides/getting-started/mismo-import.md#errors) for an example.

## Rate limit headers

Responses to authenticated requests carry these headers, for both GraphQL and REST. `401` and `403` responses don't carry them.

| Header | Sent on | Meaning |
| - | - | - |
| `Retry-After` | Limited requests only | Whole seconds to wait before retrying |
| `X-RateLimit-Limit` | Every response | The sustained rate per minute for this operation |
| `X-RateLimit-Remaining` | Every response | Requests you can still send right now |
| `X-RateLimit-Reset` | Every response | When the allowance is fully refilled, as a Unix timestamp in seconds |
| `X-RateLimit-Policy` | Every response | Which limit applied, for example `pricing` |

The headers describe the limit that applied to the request. A GraphQL request that touches pricing reports the pricing limit.

## Retrying a limited request

Wait for the number of seconds in `Retry-After`, add a little random jitter, then send the same request again. Treat it as unfinished until it succeeds.

```typescript TypeScript theme={null}
async function pylonGraphQL(body: object, token: string): Promise<any> {
  for (let attempt = 0; attempt < 8; attempt++) {
    const response = await fetch("https://pylon.mortgage/graphql", {
      method: "POST",
      headers: {
        authorization: `Bearer ${token}`,
        "content-type": "application/json",
      },
      body: JSON.stringify(body),
    });
    const json = await response.json();
    const limited = json.errors?.some(
      (e: any) => e.extensions?.code === "RATE_LIMITED"
    );
    if (!limited) return json;

    const seconds = Number(response.headers.get("Retry-After") ?? "1");
    const jitterMs = Math.random() * 250;
    await new Promise((r) => setTimeout(r, seconds * 1000 + jitterMs));
  }
  throw new Error("Still rate limited after 8 attempts");
}
```

```python Python theme={null}
import random
import time

import requests


def pylon_graphql(body: dict, token: str) -> dict:
    for _ in range(8):
        response = requests.post(
            "https://pylon.mortgage/graphql",
            json=body,
            headers={"authorization": f"Bearer {token}"},
            timeout=120,
        )
        payload = response.json()
        limited = any(
            (e.get("extensions") or {}).get("code") == "RATE_LIMITED"
            for e in payload.get("errors") or []
        )
        if not limited:
            return payload

        seconds = int(response.headers.get("Retry-After", "1"))
        time.sleep(seconds + random.random() * 0.25)
    raise RuntimeError("Still rate limited after 8 attempts")
```

## Sending batches

If you price or update many records at once, pace your requests to the sustained rate rather than relying on retries.

> [!WARNING]
>
> **Don't move on to the next batch as soon as a batch "finishes".** A limited request returns in a few milliseconds. If your client waits for a batch to come back and then immediately sends the next one, a batch full of rejections comes back almost at once. The next batch is sent straight away and rejected too, and the loop quickly sends hundreds of requests that all fail. Retry limited requests after `Retry-After` instead of counting them as finished.

To stay under the limit with batches, start each batch no sooner than the batch size multiplied by the time between requests. Take the sustained rate from `X-RateLimit-Limit`:

```
wait = max(time the last batch took, batch size × 60 s ÷ sustained rate per minute)
```

You can also slow down before you reach the limit by watching `X-RateLimit-Remaining`. When it gets close to zero, pause until enough allowance has refilled.

## Related

* [Authentication best practices](https://docs.pylon.mortgage/guides/getting-started/authentication/auth-best-practices.md)
* [Polling for loan updates](https://docs.pylon.mortgage/recipes/loan-updates.md#rate-limiting)
* [MISMO import errors](https://docs.pylon.mortgage/guides/getting-started/mismo-import.md#errors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.