Enhanced HTTP Error Handling for Fewsats SDK

[positiveblue]

Goal

Improve the SDK's error handling to better serve both traditional Python developers and AI/LLM integrations by providing more detailed error information and structured responses.

Context

The current SDK implementation returns raw httpx.Response objects which require manual processing and don't provide detailed error information when things go wrong. This becomes particularly problematic when integrating with AI agents and LLMs that work better with structured data. The proposed solution would implement an enhanced exception handling system that returns parsed JSON data on success and provides comprehensive error details through a custom FewsatsHTTPError class. This approach maintains familiar Python error handling patterns while offering the detailed feedback needed for effective debugging and automated error recovery.

Technical Design Document

[stian-a-johansen]

Would love to see improvement on this.

It's currently impossible to debug implementations - all we can see is the HTTP error codes: <Response [500 Internal Server Error]> every time we attempt a direct lightning payments with fs.pay_lightning() (unless we specify a US dollar amount that happens to differ too much from the number of sats in the invoice in which case we get a 400 with an error message..)

The pay_offer() function reports they get a 422 back from the payment details endpoints, but I cannot see the request that's being made so it's hard to see what kind of invalid body is being sent there.