docs(errors): document problem-details and 422 mapping

- Describe the application/problem+json body following RFC 9457
- Document the 422 validation failure with reasons on error.cause
- Mirror the default behavior changes in Indonesian

Author: NeaByteLab

docs/error-handling/default-behavior.md

@@ -28,7 +28,7 @@ await router.serve(8000)
 
 The default error response (without custom `router.catch()`) follows the client's `Accept` header:
 
-- **Accept includes `application/json`** → JSON body: `{ error, path, statusCode }`
+- **Accept includes `application/json` or `application/problem+json`** → a problem-details body `{ type, title, status, instance }` sent as `application/problem+json`
 - **Otherwise** → HTML body: simple error page with status and message (escaped)
 
 Also:
@@ -39,13 +39,16 @@ Also:
 ```typescript
 // Example default response (client requests JSON)
 // Status: 404
-// Body: { "error": "...", "path": "/api/foo", "statusCode": 404 }
+// Content-Type: application/problem+json
+// Body: { "type": "about:blank", "title": "Not Found", "status": 404, "instance": "/api/foo" }
 
 // Example default response (client does not request JSON)
 // Status: 404
 // Body: HTML with <title>404</title> and error message
 ```
 
+The problem-details shape follows [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), where `type` is a problem URI, `title` is a short summary, `status` repeats the code, and `instance` carries the request path. A custom `router.catch()` replaces this body with whatever shape suits the client, covered in [Error Object Details](/error-handling/object-details).
+
 ## Error Scenarios
 
 Default error handling covers all error types that can occur during request processing:
@@ -79,6 +82,20 @@ When the path matches a route but the method has no handler, the response is `40
 
 `HEAD` is added automatically whenever a `GET` handler exists.
 
+### 422 - Validation Failed
+
+When a [validation](/middleware/validation/overview) contract rejects request input, the default response adds an `errors` array listing each failure reason:
+
+```typescript
+// POST /users with an invalid body
+// Status: 422
+// Content-Type: application/problem+json
+// Body: { "type": "about:blank", "title": "...", "status": 422,
+//         "instance": "/users", "errors": ["name must not be empty"] }
+```
+
+Only a 422 carries `errors`, and every other status keeps a reason-free body. How a contract produces those reasons lives in [Reading Validated Data](/middleware/validation/reading-data#how-failures-surface).
+
 ### 500 - Server Errors
 
 When a route handler throws any error or exception:

docs/error-handling/object-details.md

@@ -141,26 +141,23 @@ export async function POST(ctx: Context): Promise<Response> {
 
 ## Validation Errors
 
-Return appropriate status codes for validation errors:
+A rejected [validation](/middleware/validation/overview) contract throws a **422 Unprocessable Content** and preserves the failure reasons on `error.cause` as a string array. The same `router.catch` handles it, so reading the reasons turns a failure into a field-level response:
 
 ```typescript twoslash
-import type { Context, DataRecord } from '@neabyte/deserve'
+import { Router } from '@neabyte/deserve'
+
+const router = new Router()
 // ---cut---
-export async function POST(ctx: Context): Promise<Response> {
-  const data = await ctx.body() as DataRecord
-  if (!data.email) {
+router.catch((ctx, error) => {
+  if (error.statusCode === 422 && Array.isArray(error.error.cause)) {
+    // Surface each validation reason
     return ctx.send.json(
-      {
-        error: 'Email is required'
-      },
-      {
-        status: 400
-      }
+      { error: 'Validation failed', reasons: error.error.cause },
+      { status: 422 }
     )
   }
-  // Process valid data...
-  return ctx.send.json({
-    success: true
-  })
-}
+  return null
+})
 ```
+
+How a contract produces those reasons lives in [Reading Validated Data](/middleware/validation/reading-data#how-failures-surface), which keeps the validation rules in one place and the response shaping here.

docs/id/error-handling/default-behavior.md

@@ -28,7 +28,7 @@ await router.serve(8000)
 
 Response error default (tanpa `router.catch()` khusus) mengikuti header `Accept` klien:
 
-- **Accept mencakup `application/json`** → body JSON: `{ error, path, statusCode }`
+- **Accept mencakup `application/json` atau `application/problem+json`** → body problem-details `{ type, title, status, instance }` dikirim sebagai `application/problem+json`
 - **Selain itu** → body HTML: halaman error sederhana dengan status dan pesan (di-escape)
 
 Juga:
@@ -39,13 +39,16 @@ Juga:
 ```typescript
 // Contoh response default (klien minta JSON)
 // Status: 404
-// Body: { "error": "...", "path": "/api/foo", "statusCode": 404 }
+// Content-Type: application/problem+json
+// Body: { "type": "about:blank", "title": "Not Found", "status": 404, "instance": "/api/foo" }
 
 // Contoh response default (klien tidak minta JSON)
 // Status: 404
 // Body: HTML dengan <title>404</title> dan pesan error
 ```
 
+Bentuk problem-details mengikuti [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), di mana `type` adalah URI masalah, `title` ringkasan singkat, `status` mengulang kodenya, dan `instance` membawa path request. Sebuah `router.catch()` khusus mengganti body ini dengan bentuk apa pun yang cocok untuk klien, dibahas di [Detail Objek Error](/id/error-handling/object-details).
+
 ## Skenario Error
 
 Penanganan error default mencakup semua jenis error yang bisa terjadi selama pemrosesan request:
@@ -79,6 +82,20 @@ Ketika path cocok dengan sebuah rute tapi metodenya tidak punya handler, respons
 
 `HEAD` ditambahkan otomatis setiap kali handler `GET` ada.
 
+### 422 - Validasi Gagal
+
+Ketika kontrak [validasi](/id/middleware/validation/overview) menolak input request, response default menambahkan array `errors` yang mendaftar tiap alasan kegagalan:
+
+```typescript
+// POST /users dengan body tidak valid
+// Status: 422
+// Content-Type: application/problem+json
+// Body: { "type": "about:blank", "title": "...", "status": 422,
+//         "instance": "/users", "errors": ["name must not be empty"] }
+```
+
+Hanya 422 yang membawa `errors`, dan setiap status lain tetap berbody tanpa alasan. Bagaimana sebuah kontrak menghasilkan alasan itu ada di [Membaca Data Tervalidasi](/id/middleware/validation/reading-data#cara-kegagalan-muncul).
+
 ### 500 - Error Server
 
 Ketika route handler melempar error atau exception apa pun: