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. This spec fixes that.
Limits are machine-readable before they are hit. Agents learn the rules before breaking them.
Every non-success response explains what happened, why, and what to do next.
Refusals include a useful next step — a cached result, an alternative endpoint, or an upgrade path.
These examples are from Siteline, a Level 4 conformant reference implementation.
{
"service": "Siteline",
"limits": {
"scan": {
"endpoint": "/api/scan",
"method": "GET",
"limits": [{
"type": "ip-rate",
"maxRequests": 10,
"windowSeconds": 3600,
"description": "10 scans per IP per hour."
}]
}
}
}
Agents learn every limit before hitting any of them.
{
"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.
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. |
Each level builds on the previous one. Start at Level 1 and work up.
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.
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.
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.
The conformance checker validates any public URL against the spec. 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).