Limitations

To ensure fair usage, optimal performance, and API stability, the Docus Lab API enforces rate limits and file size restrictions. This prevents system overloads, abuse, and excessive resource consumption while ensuring smooth API operations for all users.

1. API Rate Limits

Each API request is subject to rate limits based on the type of API key and usage tier.

Default Rate Limits

Plan	Requests per Minute	Requests per Hour
Free Tier	30 requests/min	1,000 requests/hr
Standard	100 requests/min	5,000 requests/hr
Enterprise	500 requests/min	Unlimited

💡 Exceeding Rate Limits:

If an API key exceeds the rate limit, further requests will be rejected until the limit resets.

The response will return an HTTP 429 Too Many Requests error.

📥 Example Response for Rate Limit Exceeded:

{
  "error": "Rate limit exceeded. Try again later.",
  "statusCode": 429,
  "retry_after": 60
}

🔄 How to Handle Rate Limits?

Implement exponential backoff (retry after increasing delays).

Use batch requests where possible instead of frequent small requests.

Upgrade to a higher-tier plan if your usage is high.

2. File Size Limitations

Certain API endpoints allow file uploads (e.g., lab test reports). These uploads are subject to file size limits.

File Size Limits by Endpoint

Endpoint	Max File Size	Allowed Formats
`POST /attachments`	10 MB	PDF, JPG, PNG
`GET /attachments/{visit_id}`	No limit	Returns uploaded files

📥 Example Response for File Size Exceeded:

{
  "error": "File size exceeds the 10MB limit.",
  "statusCode": 413
}

🔹 How to Avoid File Size Issues?

Compress PDF or images before uploading.

Use optimized image formats (e.g., JPG instead of PNG if possible).

Store large files externally (e.g., AWS S3) and submit only metadata to the API.

3. How to Check Rate Limit Usage?

Every API response includes rate limit headers to help you monitor usage.

Rate Limit Headers in API Response

🔍 How to Use These Headers?

Track remaining requests and avoid exceeding limits.

Use x-rate-limit-reset to determine when you can send more requests.

Implement monitoring in your app to prevent disruptions.

4. Handling API Limits and Errors

Error Type	HTTP Status Code	Solution
Rate limit exceeded	`429 Too Many Requests`	Wait for reset or reduce request frequency.
File too large	`413 Payload Too Large`	Reduce file size before upload.
Too many concurrent requests	`503 Service Unavailable`	Use retry logic and exponential backoff.

5. Best Practices for Managing API Limits

Optimize API Calls – Avoid unnecessary requests, batch when possible.

Cache Responses – Reduce repeated calls for the same data.

Monitor Usage – Track rate limits and remaining requests via headers.

Use Background Jobs for Large Tasks – Minimize real-time processing where possible.

Need Higher Limits?

For businesses with high API usage, contact us to upgrade your rate limits at support@docus.ai

This ensures uninterrupted access and better API performance!

1. API Rate Limits#

Default Rate Limits#

2. File Size Limitations#

File Size Limits by Endpoint#

3. How to Check Rate Limit Usage?#

Rate Limit Headers in API Response#

4. Handling API Limits and Errors#

5. Best Practices for Managing API Limits#

Need Higher Limits?#