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)
✅ Full URL (including query parameters) is used in signature
✅ HTTP method is uppercase and included in signature
✅ nonce is included in the signature string
✅ Using correct secret key
✅ Signature encoding is UTF-8

# Signature debug tool

def debug_signature(method, url, api_key, secret):
    import uuid
    SIGN_STRING_PATTERN = "{method}|{url}|{ts}|{nonce}"
    timestamp = int(round(time.time() * 1000))
    nonce = uuid.uuid4()
    to_sign = SIGN_STRING_PATTERN.format(method=method.upper(), url=url, ts=timestamp, nonce=nonce)
    
    print(f"Method: {method}")
    print(f"URL: {url}")
    print(f"Timestamp: {timestamp}")
    print(f"Nonce: {nonce}")
    print(f"Sign Param: {to_sign}")
    
    signature = hmac.new(
        secret.encode('utf-8'),
        to_sign.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    print(f"Generated Signature: {signature}")
    
    return {
        "key": api_key,
        "ts": str(timestamp),
        "nonce": str(nonce),
        "sign": signature
    }

1. Upload URL Expires Too Quickly

2. Project Stuck in init / preparation

3. Webhook Not Received

4. Authentication Errors

2. Project Stuck in `init` / `preparation`