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)
    }