graceful-fail
Part of SelfHeal — autonomous error recovery for AI agents.
Self-healing API proxy for AI agents. Route your HTTP calls through Graceful Fail and get structured, LLM-powered fix instructions when APIs return errors.
Instead of your agent crashing on a 422 or retrying a 503 blindly, it gets back:
{
"is_retriable": false,
"actionable_fix_for_agent": "Remove 'name' field. Add 'first_name' and 'last_name' as separate string fields.",
"suggested_payload_diff": {
"remove": ["name"],
"add": {"first_name": "string", "last_name": "string"}
},
"error_category": "validation_error"
}
Successful requests (2xx/3xx) pass through with zero overhead. You only pay when the LLM is invoked on a failed request.
Install
pip install graceful-fail
With LangChain support:
pip install 'graceful-fail[langchain]'
Quick Start
from graceful_fail import GracefulFail
gf = GracefulFail(api_key="gf_your_key")
response = gf.post("https://api.example.com/users", json={"name": "Alice"})
if response.intercepted:
# The API returned an error — here's exactly how to fix it
print(response.error_analysis.actionable_fix_for_agent)
print(response.error_analysis.suggested_payload_diff)
else:
# Success — here's the data
print(response.data)
Async Support
from graceful_fail import GracefulFailAsync
async with GracefulFailAsync(api_key="gf_your_key") as gf:
response = await gf.post("https://api.example.com/users", json={"name": "Alice"})
LangChain Integration
As a Tool (recommended for agents)
from graceful_fail.langchain import GracefulFailTool
from langchain.agents import create_react_agent
tool = GracefulFailTool(api_key="gf_your_key")
agent = create_react_agent(llm, [tool])
# Your agent now gets structured fix instructions instead of raw HTTP errors
As a Requests Wrapper
Drop-in replacement for LangChain's TextRequestsWrapper:
from graceful_fail.langchain import GracefulFailRequests
requests = GracefulFailRequests(api_key="gf_your_key")
result = requests.get("https://api.example.com/users")
requests-Compatible Session
For codebases already using requests:
from graceful_fail.patch import GracefulFailSession
session = GracefulFailSession(api_key="gf_your_key")
resp = session.post("https://api.example.com/users", json={"name": "Alice"})
print(resp.status_code)
print(resp.json())
if resp.graceful_fail_intercepted:
print(resp.error_analysis)
Response Object
Every call returns a GracefulFailResponse:
| Field | Type | Description |
|---|---|---|
status_code |
int |
HTTP status from the destination API |
intercepted |
bool |
True if the error was analyzed by the LLM |
data |
Any |
Response body (success) or full error envelope (intercepted) |
error_analysis |
ErrorAnalysis |
LLM analysis (only when intercepted=True) |
raw_response |
Any |
Original destination API response body |
credits_used |
int |
0 for pass-through, 1 for intercepted |
ErrorAnalysis Fields
| Field | Type | Description |
|---|---|---|
is_retriable |
bool |
Whether retrying the same request may succeed |
human_readable_explanation |
str |
What went wrong, in plain English |
actionable_fix_for_agent |
str |
Exact instruction for the agent |
suggested_payload_diff |
PayloadDiff |
What to change (remove/add/modify) |
error_category |
str |
validation_error, auth_error, rate_limit, etc. |
Auto-Apply Fix
if response.intercepted:
fixed_payload = response.error_analysis.suggested_payload_diff.apply(original_payload)
retry_response = gf.post(url, json=fixed_payload)
Get Your API Key
- Sign up at selfheal.dev
- Create an API key in the dashboard
- Free tier: 500 requests/month
Links
Metadata
Release files for graceful-fail 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| graceful_fail-0.4.0.tar.gz | 14.6 kB | Without provenance | Details for graceful_fail-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| graceful_fail-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for graceful_fail-0.4.0-py3-none-any.whl |
Total release size: 27.3 kB
Release files / graceful_fail-0.4.0.tar.gz
| Download URL | graceful_fail-0.4.0.tar.gz |
|---|---|
| Size | 14.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3d8431b33832652f25033c3bda68e070ffd1b24424c5bbce3b976a5c18e659af
|
|
BLAKE2b-256 checksum How to use checksums |
1e12930b58b97cede54d4b33698e9482e211f1638c90f7c654af93a9b05734ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / graceful_fail-0.4.0-py3-none-any.whl
| Download URL | graceful_fail-0.4.0-py3-none-any.whl |
|---|---|
| Size | 12.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c02f1b176c015c5c9e5f6d3383a073553cbfe5fd2ffdf9ff3e7c7803fad001ed
|
|
BLAKE2b-256 checksum How to use checksums |
0026fd1542bee7b051e1ccb7a40701674b1652a69b8943b3b5c50374a9701d71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Security for graceful-fail 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.