Errors & Rate Limits

Error Format

All error responses follow a consistent format:

{
  "success": false,
  "error": "Description of the error"
}

HTTP Status Codes

Code	Meaning
200	Success - request completed.
201	Created - resource was created successfully.
202	Accepted - file uploaded, document record will appear shortly.
400	Bad Request - missing or invalid parameters, unsupported file type, or Content-Type mismatch.
401	Unauthorized - missing or invalid API key.
403	Forbidden - API key lacks required scope or space access.
404	Not Found - resource does not exist or is not accessible.
409	Conflict - content already exists in the user's library (duplicate SHA-256 hash). Error codes: DUPLICATE_DOCUMENT, INTEGRITY_MISMATCH.
413	Payload Too Large - uploaded file exceeds the 50 MB limit.
429	Too Many Requests - rate limit exceeded (standard limits are 100/min and 1,000/hour per API key; some endpoints may apply stricter limits).
500	Internal Server Error - something went wrong on our end.

Rate Limits

API requests are rate-limited to ensure fair usage:

• 100 requests per minute per API key
• 1,000 requests per hour per API key

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709740800

Handling Rate Limits

When you receive a 429 response, wait until the time indicated by X-RateLimit-Reset (Unix timestamp) before retrying. Implement exponential backoff for robustness:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    if (response.status === 429) {
      const resetTime = response.headers.get("X-RateLimit-Reset");
      const waitMs = (resetTime * 1000) - Date.now() + 1000;
      await new Promise(r => setTimeout(r, Math.max(waitMs, 1000)));
      continue;
    }
    return response;
  }
  throw new Error("Rate limit exceeded after retries");
}

Common Error Scenarios

Error	Cause	Solution
"Invalid or missing API key"	Missing Authorization header or malformed key.	Check your API key format and header.
"Insufficient scope"	API key doesn't have the required scope.	Update key scopes in Settings > API Keys.
"Access denied to this space"	API key is restricted and can't access the requested space.	Add the space to the key's allowed spaces or use a key with broader access.
"Document not found"	Document doesn't exist or is in an inaccessible space.	Verify the document ID and your key's space access.
"File content does not match any supported format"	Uploaded file bytes don't match PDF, JPEG, PNG, or TIFF signatures.	Ensure you're uploading a valid file in a supported format.
"Content-Type mismatch"	The Content-Type header doesn't match the actual file content.	Set the correct Content-Type for your file or let your HTTP client detect it.