fix: improve error handling for hCaptcha 500 errors (Issue #7)

[JosefVacha]

Summary

Improves error handling for 500 Server Errors caused by hCaptcha protection on Udio's API endpoints. Updates documentation to inform users about the current state of the API wrapper.

Root Cause

Udio implemented hCaptcha protection on their /generate-proxy endpoint in April 2024. Automated requests without proper browser session/captcha solving now return 500 Server Error. The original code did not distinguish between general server errors and hCaptcha-related blocks.

Proposed Changes

• udio_wrapper/init.py: Enhanced make_request() method to:

  • Detect 500 errors on generate-proxy endpoint and provide specific hCaptcha-related error message
  • Add timeout parameter (30s) to prevent hanging requests
  • Add specific handling for requests.exceptions.Timeout
  • Provide actionable suggestions for users (Selenium workaround, wait for official API, etc.)

• README.md: Added "Known Issues" section documenting:

  • hCaptcha protection status
  • Current limitations of automated requests
  • Possible workarounds with appropriate warnings about ToS violations
  • Updated TODO section with browser-based authentication task

Verification Results

All syntax and code quality checks passed:

• Command: python3 -m py_compile udio_wrapper/__init__.py
• Outcome: Syntax OK

Note: The repository does not contain automated unit tests. Changes were verified through syntax validation and code review. The modifications are primarily defensive error handling and documentation updates that do not alter core functionality.

Important Note

This PR does not "auto-solve" hCaptcha as originally requested in the bounty. Based on the issue discussion:

• Browser-based solutions (Selenium) have proven unreliable
• Contributing to anti-bot system bypass may violate terms of service
• A contributor (jfarre20) declined further work due to employment policy concerns

This PR provides the best actionable solution: clear error messaging, documentation of the current state, and guidance for users seeking workarounds.