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

# Rate Limiting

> How rate limiting works and best practices for staying within limits.

# Rate Limiting

The PixCraft API uses monthly usage limits based on your plan. Usage is tracked **per account** (not per API key), and only **pattern generation** counts as a use.

## Limits by plan

| Plan       | Monthly uses | When limit is reached                                       |
| ---------- | ------------ | ----------------------------------------------------------- |
| Starter    | 500          | API and widget stop generating designs until the next month |
| Business   | 2,000        | API and widget stop generating designs until the next month |
| Enterprise | Unlimited    | —                                                           |

## What counts as a use

Only **generating a pattern/design** counts as a use:

| Action                                                      | Counts as use? |
| ----------------------------------------------------------- | -------------- |
| `POST /api/v1/generate` (generate pattern)                  | **Yes**        |
| Widget: user clicks "Generate"                              | **Yes**        |
| `POST /api/v1/generate/pdf` (download PDF)                  | No             |
| Widget load / validation                                    | No             |
| `GET /api/v1/usage`                                         | No             |
| `GET /api/v1/capabilities`, `/niches`, `/colors`, `/health` | No             |

## How it works

* Usage is tracked at the **account level** — all your API keys and widgets share the same monthly counter
* Usage resets on the 1st of each month
* When you reach your limit, the API returns `429 RATE_LIMIT_EXCEEDED` and the widget will not generate new designs
* You will receive an **email notification** when you are close to your limit (\~50 uses remaining)
* You will receive another **email notification** when you reach the limit

## Checking your usage

Call `GET /api/v1/usage` to see how many uses you have remaining:

```bash theme={null}
curl https://www.pixcraft.es/api/v1/usage \
  -H "Authorization: Bearer px_live_your_key"
```

```json theme={null}
{
  "calls_used": 243,
  "calls_limit": 2000,
  "calls_remaining": 1757,
  "reset_date": "2025-05-01"
}
```

## Handling 429 errors

When rate limited, do **not** retry — the limit resets at the beginning of the next month. Instead, inform your users or upgrade your plan.

```javascript theme={null}
const response = await fetch('https://www.pixcraft.es/api/v1/generate', { ... });

if (response.status === 429) {
  // Monthly limit reached — do not retry
  console.log('Monthly usage limit reached. Upgrade your plan or wait until next month.');
}
```

## Best practices

1. **Cache results** — If the same image + parameters are requested again, serve from cache instead of calling the API
2. **Monitor usage** — Check `/usage` periodically and set up alerts when approaching your limit
3. **Use appropriate plans** — If you consistently hit your limit, consider upgrading to avoid service interruptions