Methodology
API error responses
ia.api-errors · 4.22
Act
SHOULD
Recommendation
AR-ACT-02
Why it matters
Agents call APIs programmatically and cannot recover from an HTML error page. A JSON problem-details body with a machine-readable code and a human-readable message lets them branch on failures instead of guessing.
How to fix it
Return RFC 9457 problem details as JSON for API errors.
-
Return application/problem+json for each 4xx and 5xx response of the API.
{"type": "https://example.com/problems/not-found", "title": "Not found", "status": 404, "detail": "No such resource"}
Verify
curl -s https://{domain}/api/isagentready-missing-check | jq -e '.status or .error'
Expected: exit code 0
Run a new scan for this checkpoint:
isagentready results {domain} --checkpoint ia.api-errors
Details Mapping, lifecycle and references
- AR mapping
- Partial match
- Evidence source
- agentready.org AR-ACT-02
- Score role
- Core
- Introduced
- 2026-08-25
- Methodology version
- 2026-10-22