Skip to main content

​
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 TypeValue
Request Rate1 request per second per IP
Daily LimitUnlimited (pay-as-you-go)

​
/v1/playground (Unauthenticated)

Limit TypeValue
Request Rate1 request per second per IP
Daily Credits10 credits per day per IP
Credits reset at midnight UTC each day.

​
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

DocumentEstimated SizeCredits
2-page invoice PDF~200KB1-2 credits
10-page contract PDF~1MB5-10 credits
Simple receipt PDF~50KB1 credit

​
Rate Limit Headers

When you hit a rate limit, the API returns HTTP status 429 with details: 
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1

{
  "detail": "Rate limit exceeded. Please retry after 1 second."
}
For credit limits (playground): 
{
  "detail": "Daily credit limit exceeded. Resets at midnight UTC."
}

​
Handling Rate Limits

​
Automatic Retry (SDKs)

Both official SDKs implement automatic retry with exponential backoff: 
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)

​
Manual Retry (cURL/Custom)

Implement exponential backoff in your own code: 
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

Batch Processing

When processing multiple documents, add delays between requests to stay under rate limits.

Queue System

For high-volume processing, implement a queue that respects rate limits.

Error Handling

Always handle 429 errors gracefully with retry logic.

Monitor Usage

Track your credit usage in the dashboard to avoid unexpected limits.

​
Example: Rate-Limited Batch Processing

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:
LimitValue
Maximum file size10 MB
Supported formatsPDF, DOCX
Files exceeding 10 MB will receive a 400 Bad Request error: 
{
  "detail": "File size exceeds maximum limit of 10MB"
}

​
Increasing Limits

Need higher rate limits for your use case? Contact us:
  • Email: [email protected]
  • Enterprise plans: Custom rate limits and dedicated infrastructure available
Enterprise customers can get dedicated API endpoints with higher throughput and SLA guarantees.