API Reference
Start typing to search…

Troubleshooting

Resolve common issues and fix errors quickly.

1. Upload URL Expires Too Quickly

Problem: "Upload URL expired" error after 10 minutes

Root Cause: S3 pre-signed URLs have X-Amz-Expires=600 (10 minutes)

Solutions:

  • Complete the file upload within 10 minutes of receiving the URL
  • For large files, request a new upload URL if needed
  • Implement upload progress monitoring

2. Project Stuck in init / preparation

Problem: Project remains in init or preparation status for extended periods

Potential Causes:

  • Document processing issues (corrupted file, unsupported format)
  • High server load during peak hours
  • Document too complex (too many pages/images)
# Implement robust status checking with timeout

def wait_for_status(project_uuid, target_status, max_wait=600):
    start_time = time.time()
    while time.time() - start_time < max_wait:
        response = make_request("GET", f"/openapi/v1/project/{project_uuid}/info")
        current_status = response.json()["data"]["progressStatus"]
        
        if current_status == target_status:
            return True
        elif current_status == "error":
            # Get failure details
            error_info = response.json()["data"].get("error_details", "Unknown error")
            raise Exception(f"Project failed: {error_info}")
        
        # Exponential backoff
        wait_time = min(30, 5 * (2 ** (int((time.time() - start_time) / 60))))
        time.sleep(wait_time)
    
    raise Exception(f"Timeout waiting for status {target_status}")

3. Webhook Not Received

Problem: Completion webhooks are not being delivered

Checklist:

  • ✅ Webhook URL is publicly accessible (not localhost)
  • ✅ Webhook endpoint returns HTTP 200 status
  • ✅ Webhook URL uses HTTPS (recommended)
  • ✅ Response time under 30 seconds
  • ✅ No rate limiting on webhook endpoint
# Simple webhook test endpoint

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook-test', methods=['POST'])
def webhook_test():
    print(f"Received webhook: {request.get_json()}")
    return jsonify({"status": "received"}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

4. Authentication Errors

Problem: "Invalid signature" or authentication failures

Debug Checklist:

  • ✅ Timestamp is current (within 5 minutes)
  • ✅ URL path includes query parameters in signature
  • ✅ HTTP method matches exactly
  • ✅ Using correct secret key
  • ✅ Signature encoding is UTF-8
# Signature debug tool

def debug_signature(method, url_path, api_key, secret):
    timestamp = int(datetime.now().timestamp() * 1000)
    sign_param = f"{method}|{url_path}|{timestamp}"
    
    print(f"Method: {method}")
    print(f"URL Path: {url_path}")
    print(f"Timestamp: {timestamp}")
    print(f"Sign Param: {sign_param}")
    
    signature = hmac.new(
        secret.encode('utf-8'),
        sign_param.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    print(f"Generated Signature: {signature}")
    
    return {
        "key": api_key,
        "sign": signature,
        "ts": str(timestamp)
    }