Graceful Boundaries
A specification for how services communicate their operational limits to humans and autonomous agents.
Every unclear error response generates follow-up traffic. A vague 429 causes blind retries. A vague 403 causes credential cycling. When autonomous agents are the caller, the waste compounds. Version 1.3.0 adds optional extension discovery for consequential agent actions while keeping the core conformance model stable.
Proactive Discovery
Limits are machine-readable before they are hit. Agents learn the rules before breaking them.
Structured Refusal
Every non-success response explains what happened, why, and what to do next.
Constructive Guidance
Refusals include a useful next step — a cached result, an alternative endpoint, or an upgrade path.
See it in action
These examples are from Siteline, a Level 4 conformant reference implementation.
Discovery endpoint
{
"service": "Siteline",
"limits": {
"scan": {
"endpoint": "/api/scan",
"method": "GET",
"limits": [{
"type": "ip-rate",
"maxRequests": 10,
"windowSeconds": 3600,
"description": "10 scans per IP per hour."
}, {
"type": "resource-dedup",
"maxRequests": 1,
"windowSeconds": 86400,
"returnsCached": true,
"description": "Repeat scans return cached results."
}]
}
},
"extensions": {
"actionBoundaries": "/.well-known/action-boundaries"
}
}
Agents learn every limit before hitting any of them, and can follow optional same-origin extension links.
Structured refusal (429)
{
"error": "rate_limit_exceeded",
"detail": "You can run up to 10 scans per hour.
Try again in 2400 seconds.",
"limit": "10 scans per IP per hour",
"retryAfterSeconds": 2400,
"why": "Rate limits keep the service available
for everyone and prevent abuse.",
"alternativeEndpoint": "/api/result?id=example.com"
}
The caller knows what, when, why, and where to go instead.
Conformance levels
Services self-declare a conformance level. The eval suite validates the claim.
| Level | What it requires |
|---|---|
| N/A | No API endpoints, rate limits, or agentic interaction surface. |
| Level 0 | Limits exist but are not described per this specification. |
| Level 1 | All non-success responses include error, detail, and why. All 429s add limit and retryAfterSeconds. |
| Level 2 | Level 1 + a limits discovery endpoint. |
| Level 3 | Level 2 + refusal responses include constructive guidance when applicable. |
| Level 4 | Level 3 + successful responses include proactive RateLimit headers. |
Which level should you target?
- No API or agentic surface? Declare N/A — takes 5 minutes.
- API with rate limits? Start at Level 1. This is the minimum useful level.
- Agents call your API? Target Level 2 so agents learn the rules before breaking them.
- Want to reduce 429 traffic? Target Level 3 — offer alternatives instead of bare refusals.
- High-traffic API? Target Level 4 — callers self-throttle before hitting limits.
Current in v1.3.0
Graceful Boundaries 1.3.0 keeps the Level 1 through Level 4 conformance model unchanged and adds optional extension discovery for services where agents may take consequential actions.
Extension discovery
{
"service": "Example Service",
"description": "Public API and commercial service.",
"conformance": "level-4",
"extensions": {
"actionBoundaries": "/.well-known/action-boundaries",
"commercialBoundaries": "/.well-known/commercial-boundaries"
},
"limits": {}
}
Extension URLs must be relative paths or same-origin absolute URLs. Unknown extension keys should be ignored.
Action refusal
{
"error": "approval_required",
"detail": "A human must approve purchases over
100 USD before the agent can continue.",
"why": "Purchases above this threshold create
financial obligations that require
explicit approval.",
"action": "purchase",
"approvalUrl": "/approve/purchase/abc123",
"humanUrl": "/support"
}
Action Boundaries describe authority, approval, recourse, and audit expectations. They are declarations, not payment rails, checkout, identity proof, or certification.
Optional documents for services where agents may create accounts, change permissions, purchase, cancel, request refunds, or perform other consequential actions.
The first Action Boundaries profile. It describes whether buyer agents can understand, evaluate, transact, modify, cancel, and resolve a commercial relationship without defining payment execution.
See the Action Boundaries draft and examples.
Getting started
Each level builds on the previous one. Start at Level 1 and work up. Add optional extension discovery only when your service publishes same-origin boundary documents for agent actions.
Add error, detail, and why to every non-success response. Add limit and retryAfterSeconds to 429s.
Add a /api/limits endpoint that returns all enforced limits as structured JSON. If applicable, link same-origin extension documents from extensions.
Add guidance fields to refusals: cachedResultUrl, alternativeEndpoint, upgradeUrl.
Add RateLimit and RateLimit-Policy headers to successful responses.
For code samples at each level, see the implementation guide.
Add to your AI coding workflow
Drop this into your project's CLAUDE.md or AI context file. Any AI assistant working in your codebase will apply Graceful Boundaries automatically.
## Error Responses This project follows the Graceful Boundaries specification (https://gracefulboundaries.dev). All non-success HTTP responses MUST include `error` (snake_case string), `detail` (human-readable), and `why` (the reason). All 429 responses MUST also include `limit` and `retryAfterSeconds`. See spec for response class requirements and constructive guidance.
Evaluate your API
The conformance checker validates any public URL against the spec. Version 1.3.0 includes stricter response-field checks, discovery schema validation, safe guidance URL checks, and optional Action Boundaries validation. No dependencies required.
git clone https://github.com/snapsynapse/graceful-boundaries.git cd graceful-boundaries node evals/check.js https://your-service.com
Reference implementation: Siteline (Level 4). Unit suite: 173 tests.