Yannis JSON errors

JSON API errors on yannis.dev use RFC 9457 problem details with Content-Type: application/problem+json. The core fields are type, title, status, detail, and instance. Yannis also returns code and hint extension fields so agents can branch on a stable machine value and show a practical recovery step without parsing prose.

Problem type URLs live on this page. The current public codes are api.not_found for unknown API routes, http.method_not_allowed when a method is not supported, http.forbidden_origin when an MCP Origin header is not http or https, http.not_acceptable when a requested media type cannot be produced, request.invalid_json when a body cannot be parsed, mcp.unsupported_protocol_version for unsupported MCP protocol headers, rate_limit.exceeded for 429 responses, and server.error for unexpected failures.

A typical response is a JSON object such as {"type":"https://yannis.dev/developers/errors#api.not_found","title":"API route not found","status":404,"detail":"The requested API path is not published on yannis.dev.","instance":"/api/example","code":"api.not_found","hint":"Read https://yannis.dev/openapi.json and retry a documented path."}

HTML pages still return HTML for browsers. API paths and machine-readable resources return structured JSON errors where the site controls the response. If an intermediary or static host produces an error before this code runs, check /openapi.json for the canonical endpoint list and email hello@yannis.dev with the failing URL.

Problem types

api.not_found

Use a documented path from /openapi.json or /api/status.json.

http.method_not_allowed

Retry with a method listed in the Allow header.

http.forbidden_origin

Retry from an http or https client origin, or omit Origin for server-to-server MCP calls.

http.not_acceptable

Request text/html, text/markdown, application/json, or application/problem+json as documented.

request.invalid_json

Send syntactically valid JSON with the required fields from the OpenAPI schema.

mcp.unsupported_protocol_version

Use a supported MCP-Protocol-Version header from the MCP docs.

rate_limit.exceeded

Honor Retry-After first, then the RateLimit response hints.

server.error

Retry later, then email hello@yannis.dev with the URL and timestamp if it persists.