# Structured errors for JSON requests

> An agent that asks for JSON and gets an HTML error page has to read a page meant for people. RFC 9457 defines a JSON error format.

- Source: /checks/structured-errors
- Site: AgenticWebScore
- Language: English

---
An agent that asks for JSON and gets an HTML error page has to read a page meant for people. RFC 9457 defines a JSON error format.

Standard status: Adopted. A ratified standard with real deployment. Standard: [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html).

- Kind: Scored check
- Part of the score: Agent conventions: 30% of the score. A convention never holds a level.
- Module: Every site
- Who reads it today: API clients and agents that send Accept: application/json. No search engine reads it.
- Effect on Google Search: None. No Google Search documentation says Google reads it.

| Property | Value |
| --- | --- |
| Check id | `structured-errors` |
| Dimension | Discoverability |
| Part | Agent conventions |
| Tier | Recommended. Counts its weight once. |
| Weight | 1 |
| Maturity | Adopted. A ratified standard with real deployment. |
| Publishing skill | `problem-details` |
| Standards | RFC 9457 |

## Sources

- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html), IETF, July 2023
- [RFC 9110, 12.5.1: Accept](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept), IETF

## What is measured

The scanner requests the path of not-found-status a second time, with Accept: application/json, application/problem+json;q=0.9, */*;q=0.1, and reads the status, the Content-Type and the body of the answer. Present = an error status (4xx or 5xx) with a JSON type, application/problem+json (RFC 9457), application/json or another +json type, and a body that parses as a JSON object or is cut at the read limit. Partial = an error status with a JSON body served with another type or with none, or a JSON array served as JSON. Served with an error = an error status with a JSON type whose body does not parse as a JSON object. Not used = a status below 400, such as a 2xx, whatever the body, which tells a JSON client the path exists; or an HTML page, another type, or no body. Not measured = 406, which refuses the scan's Accept header; 429; 401, 403, 407 or a 5xx status with a body that is not JSON; a redirect to another site, which is not followed; or no answer. Present earns the check's points in the agent-conventions part, and Partial half of them.

## Reproduce it yourself

You do not have to take our word for any of this. Run the same measurement against your own domain:

```bash
ORIGIN=https://example.com
MISSING="/aws-probe-$(head -c 6 /dev/urandom | od -An -tx1 | tr -d ' \n')"
curl -sS -D - -A 'AgenticWebScore/0.3 (+https://agenticwebscore.com/bot)' -H 'Accept-Language: en' -H 'Accept: application/json, application/problem+json;q=0.9, */*;q=0.1' "$ORIGIN$MISSING" | head -20
```

## The fix

This is an example written for example.com. Where the scan can build the fix from your own site, the report shows that version instead.

```json
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Nothing is published at this address."
}
```

> Send this with Content-Type: application/problem+json and the status 404 when a request for a missing path asks for JSON. Browsers can keep the HTML page (RFC 9457).

## Standards referenced

- `RFC 9457`

## Related checks

| Check | Kind | Maturity | Same skill |
| --- | --- | --- | --- |
| `reachable` — Readable homepage | Scored check | Adopted | — |
| `sitemap-xml` — XML sitemap | Scored check | Adopted | — |
| `llms-txt` — /llms.txt published and well-structured | Scored check | Draft | — |
| `link-headers` — Discovery via Link response headers | Scored check | Adopted | — |
| `dns-aid` — DNS-AID discovery record | Unscored check | Experimental | — |
| `canonical` — Canonical URL | Scored check | Adopted | — |
| `http-caching` — HTTP caching of the homepage | Scored check | Adopted | — |
| `indexing-directives` — Homepage indexable: no noindex directive | Scored check | Adopted | — |