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

# Rate Limits

> Understanding Parsefy's rate limiting and credit system

## Overview

Parsefy implements rate limiting to ensure fair usage and API stability. There are two types of limits:

1. **Request Rate Limits**: How many requests you can make per second
2. **Credit Limits**: How many document pages you can process (playground only)

## Rate Limits by Endpoint

### `/v1/extract` (Authenticated)

| Limit Type   | Value                       |
| ------------ | --------------------------- |
| Request Rate | 1 request per second per IP |
| Daily Limit  | Unlimited (pay-as-you-go)   |

### `/v1/playground` (Unauthenticated)

| Limit Type    | Value                       |
| ------------- | --------------------------- |
| Request Rate  | 1 request per second per IP |
| Daily Credits | 10 credits per day per IP   |

<Note>
  Credits reset at midnight UTC each day.
</Note>

## Understanding Credits

Credits are Parsefy's unit for measuring document processing:

```
1 credit ≈ 1 page of a document
```

Credit calculation is based on file size:

* **PDF**: Approximately 100KB per page
* **DOCX**: Approximately 50KB per page

### Example Credit Usage

| Document             | Estimated Size | Credits      |
| -------------------- | -------------- | ------------ |
| 2-page invoice PDF   | \~200KB        | 1-2 credits  |
| 10-page contract PDF | \~1MB          | 5-10 credits |
| Simple receipt PDF   | \~50KB         | 1 credit     |

## Rate Limit Headers

When you hit a rate limit, the API returns HTTP status `429` with details:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
```

```json theme={null}
{
  "detail": "Rate limit exceeded. Please retry after 1 second."
}
```

For credit limits (playground):

```json theme={null}
{
  "detail": "Daily credit limit exceeded. Resets at midnight UTC."
}
```

## Handling Rate Limits

### Automatic Retry (SDKs)

Both official SDKs implement automatic retry with exponential backoff:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from parsefy import Parsefy

    # The SDK automatically retries on 429 errors
    client = Parsefy()

    # This will retry up to 3 times with backoff
    result = client.extract(file="document.pdf", schema=Schema)
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    import { Parsefy } from 'parsefy';

    // The SDK automatically retries on 429 errors
    const client = new Parsefy();

    // This will retry with exponential backoff
    const result = await client.extract({
      file: './document.pdf',
      schema,
    });
    ```
  </Tab>
</Tabs>

### Manual Retry (cURL/Custom)

Implement exponential backoff in your own code:

```python theme={null}
import time
import httpx

def extract_with_retry(file_path, schema, max_retries=3):
    for attempt in range(max_retries):
        response = httpx.post(
            "https://api.parsefy.io/v1/extract",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": open(file_path, "rb")},
            data={"output_schema": json.dumps(schema)}
        )
        
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 1))
            wait_time = retry_after * (2 ** attempt)  # Exponential backoff
            time.sleep(wait_time)
            continue
            
        return response.json()
    
    raise Exception("Max retries exceeded")
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Batch Processing" icon="layer-group">
    When processing multiple documents, add delays between requests to stay under rate limits.
  </Card>

  <Card title="Queue System" icon="clock">
    For high-volume processing, implement a queue that respects rate limits.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    Always handle 429 errors gracefully with retry logic.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Track your credit usage in the dashboard to avoid unexpected limits.
  </Card>
</CardGroup>

### Example: Rate-Limited Batch Processing

```python theme={null}
import time
from parsefy import Parsefy
from pydantic import BaseModel

client = Parsefy()

class Invoice(BaseModel):
    invoice_number: str
    total: float

documents = ["invoice1.pdf", "invoice2.pdf", "invoice3.pdf"]

for doc in documents:
    result = client.extract(file=doc, schema=Invoice)
    print(f"{doc}: {result.data.invoice_number}")
    
    # Respect rate limit: wait 1 second between requests
    time.sleep(1)
```

## File Size Limits

In addition to rate limits, there are file size restrictions:

| Limit             | Value     |
| ----------------- | --------- |
| Maximum file size | 10 MB     |
| Supported formats | PDF, DOCX |

Files exceeding 10 MB will receive a `400 Bad Request` error:

```json theme={null}
{
  "detail": "File size exceeds maximum limit of 10MB"
}
```

## Increasing Limits

Need higher rate limits for your use case? Contact us:

* **Email**: [support@parsefy.org](mailto:support@parsefy.org)
* **Enterprise plans**: Custom rate limits and dedicated infrastructure available

<Info>
  Enterprise customers can get dedicated API endpoints with higher throughput and SLA guarantees.
</Info>