errorpage

Principles

# すべて不適切
HTTP/1.1 200 OK          ← 本文に <h1>404 Not Found</h1> があっても無意味
HTTP/1.1 200 OK          ← 本文が { "status": 404 } でも無意味
HTTP/1.1 302 Found       ← 代替がないのにトップへ飛ばす
Location: /

• https://www.rfc-editor.org/rfc/rfc9110.html
• https://www.rfc-editor.org/rfc/rfc9457.html

Selecting a Status Code

• 404 Not Found — The URL is incorrect, has no route, or its existence cannot be confirmed. It indicates that no representation currently exists, without explicitly stating that the resource has been permanently removed. It can also be used when revealing the existence of a resource is undesirable.
• 410 Gone — The resource existed in the past and has been intentionally and permanently retired. Choose it only when it is certain that the resource will not be restored and no replacement exists.
• 301 Moved Permanently / 308 Permanent Redirect — Use only when a reliably equivalent destination exists.
• 503 Service Unavailable — Maintenance, overload, or a dependency failure. The service is temporarily unavailable.
• 401 Unauthorized — Authentication information is required or insufficient.
• 403 Forbidden — Access is unavailable even when the requester is authenticated.

Implementation Order

1. At the routing layer, capture requests other than those for known pages, APIs, and static files.
2. Use 301 or 308 only for mappings from old URLs to equivalent new URLs.
3. Use 410 only for public URLs whose retirement has been confirmed.
4. Use 404 for all other unknown URLs.
5. Select the response body—HTML, Markdown, or application/problem+json—according to Accept.
6. Add Vary: Accept to prevent different representations from being confused in the cache.
7. Collect 404 logs and examine referrers, frequently requested URLs, and bot traffic to guide link corrections and redirects.

HTML Representation

<!doctype html>
<html lang="ja">
  <head>
    <meta charset="utf-8">
    <title>ページが見つかりません | Example</title>
    <meta name="robots" content="noindex">
  </head>
  <body>
    <main>
      <h1>ページが見つかりません</h1>
      <p>URL が間違っているか、ページが移動・削除された可能性があります。</p>
      <nav aria-label="次の操作">
        <a href="/">ホームへ戻る</a>
        <a href="/search">サイト内を検索</a>
        <a href="/docs/">ドキュメント</a>
        <a href="/sitemap.xml">サイトマップ</a>
      </nav>
    </main>
  </body>
</html>

• Explicitly state that the resource was not found. Saying only that an error occurred does not explain the cause.
• Provide links to the homepage, site search, major categories, documentation, and contact information.
• If displaying the requested URL, do not expose query strings, tokens, or email addresses unchanged.
• Follow the brand style while ensuring that the error page is not confused with a regular content page.
• noindex is not mandatory. The primary objective is to return the correct 4xx status. Add noindex if you want to prevent the 404 template itself from appearing in search results.
• Do not use robots.txt to completely block crawling of groups of nonexistent URLs. Doing so makes it impossible to verify that they return 404 or 410. To remove unwanted pages, first provide correct 404 and 410 responses, remove them from the sitemap, and fix internal links.

API Representation

HTTP/1.1 404 Not Found
Content-Type: application/problem+json; charset=utf-8
Cache-Control: no-store

{
  "type": "https://example.com/problems/resource-not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No resource matches this URL. See https://example.com/docs/.",
  "instance": "urn:request:01JABC..."
}

• The status in the body is advisory. It must always match the actual HTTP status line.
• The detail should explain how clients can correct the problem rather than expose debugging information.
• Do not require clients to parse strings and use them for control flow. Decisions should be based on the HTTP status and a stable type URI.
• When possible, make the type URI point to human-readable documentation.
• Ensure that clients can safely ignore unknown extension fields.

Markdown Representation

HTTP/1.1 404 Not Found
Content-Type: text/markdown; charset=utf-8
Vary: Accept
Cache-Control: no-store

# Not found

This URL does not exist.

- [Documentation index](/docs/)
- [Sitemap](/sitemap.xml)
- [LLM guidance](/llms.txt)

HEAD

Caching

• URLs that are completely retired and will never return — Use 410 with a short-to-medium cache lifetime.
• Typos, random URLs, or dynamically generated URL spaces — Use 404 with no-store or a short max-age.
• URLs that intentionally return 404 for authorization purposes — Use private, no-store to prevent information leakage through shared caches.
• When a CDN is present, verify the 404 behavior of the browser, CDN, and application layers separately.

Do Not Leak Information

• Stack traces, exception messages, or source map URLs.
• Framework names and versions, internal IP addresses, or hostnames.
• Repository paths, database table names, or cloud bucket names.
• User IDs, email addresses, or session information.
• Response differences that reveal that a nonpublic resource exists but the requester lacks permission.

Validation

# ステータスだけ見る
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/no-such-path

# リダイレクトを追わず最初の応答を見る
curl -sS -D - -o /dev/null https://example.com/no-such-path

# HEAD でも同じか
curl -sSI https://example.com/no-such-path

# API 表現
curl -sS -i -H 'Accept: application/problem+json' https://example.com/api/no-such-path

# Markdown 表現
curl -sS -i -H 'Accept: text/markdown' https://example.com/no-such-path

• The status line is genuinely 404 or the intended 410.
• There are no unintended 30x responses.
• The Content-Type matches the actual body. For JSON, it should be application/problem+json.
• If the body includes a status field, it matches the HTTP status.
• The HTML provides users with a way to recover, and the Markdown links are valid.
• The body contains no secrets or internal information.
• HEAD returns the same failure status without a body.
• The result is identical when accessed through the production domain via a CDN or proxy.