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

# Rate Limits

> Understanding API rate limits and how to handle them

Triqai applies rate limits to ensure fair usage and maintain service reliability. Rate limits vary by plan and are applied per organization.

## Rate Limits by Plan

| Plan           | Requests per Minute (RPM) | Requests per Second |
| -------------- | ------------------------- | ------------------- |
| **Free**       | 60 RPM                    | 1 RPS               |
| **Starter**    | 300 RPM                   | 5 RPS               |
| **Growth**     | 600 RPM                   | 10 RPS              |
| **Business**   | 1,200 RPM                 | 20 RPS              |
| **Enterprise** | Custom                    | Custom              |

<Note>
  Rate limits use a token bucket algorithm (requests per second) combined with a
  concurrent in-flight request cap per organization.
</Note>

## Rate Limit Headers

Every API response includes rate limit information in the headers:

| Header                              | Description                                     |
| ----------------------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`                 | Maximum requests allowed per window             |
| `X-RateLimit-Remaining`             | Requests remaining in current window            |
| `X-RateLimit-Reset`                 | ISO timestamp when the limit resets             |
| `X-RateLimit-Scope`                 | Which limit was applied: `rps` or `concurrency` |
| `X-RateLimit-Concurrency-Limit`     | Maximum concurrent in-flight requests allowed   |
| `X-RateLimit-Concurrency-Remaining` | Concurrent request slots remaining              |

Example response headers:

```
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 2026-01-19T10:30:01.000Z
X-RateLimit-Scope: rps
```

## Rate Limit Exceeded

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Maximum 10 requests per second. Retry after 2 seconds."
  },
  "meta": {
    "generatedAt": "2026-01-19T10:30:00Z",
    "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a123",
    "version": "1.3.13"
  }
}
```

Additional headers on 429 responses:

| Header        | Description                     |
| ------------- | ------------------------------- |
| `Retry-After` | Seconds to wait before retrying |

## Best Practices

<AccordionGroup>
  <Accordion title="Batch requests when possible" icon="layer-group">
    Instead of enriching transactions one at a time in rapid succession, batch
    them and process at a controlled rate.
  </Accordion>

  <Accordion title="Use webhooks for async processing" icon="bell">
    For large batches, consider processing asynchronously rather than blocking
    on immediate results.
  </Accordion>

  <Accordion title="Monitor your usage" icon="chart-line">
    Track rate limit metrics in your dashboard to understand usage patterns and
    plan capacity.
  </Accordion>

  <Accordion title="Upgrade before hitting limits" icon="arrow-up">
    If you're consistently hitting rate limits, consider upgrading your plan for
    higher limits.
  </Accordion>
</AccordionGroup>

## Upgrading Rate Limits

If you need higher rate limits:

1. **Upgrade your plan**: Higher tiers include increased limits
2. **Contact sales**: For enterprise needs, we offer custom rate limits

<Card title="View Pricing" icon="credit-card" href="https://www.triqai.com/pricing">
  Compare plans and rate limits
</Card>

## Rate Limits Per Endpoint

All authenticated endpoints share the same rate limit pool. The limits apply to:

* `POST /v1/transactions/enrich`
* `GET /v1/transactions`
* `GET /v1/transactions/{id}`
* `DELETE /v1/transactions/{id}`
* `GET /v1/categories`
* `GET /v1/merchants/{id}`
* `GET /v1/locations/{id}`
* `GET /v1/intermediaries/{id}`
* `POST /v1/report-issue`

<Tip>
  Read-only endpoints (GET requests) count toward the same limit as enrichment
  requests. Design your application to minimize unnecessary API calls.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Credits" icon="coins" href="/platform/credits">
    Learn about credit consumption and billing
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle rate limits and other errors gracefully
  </Card>
</CardGroup>