feat(api): standardize errors as problem details

2026-08-01 14:42:19 -04:00
parent 40abab7abc
commit 2657399628
16 changed files with 441 additions and 17 deletions
@@ -0,0 +1,43 @@
+# API error contract
+
+Application-owned HTTP APIs use Problem Details per RFC 7807 / RFC 9457, matching `game-ingest-server`.
+
+Every error response has media type `application/problem+json` and the shape:
+
+```json
+{
+  "type": "urn:error:invalid-velocity-access-request",
+  "title": "Invalid Velocity access request",
+  "status": 400,
+  "detail": "The request body does not match the required Velocity access contract.",
+  "instance": "/api/velocity/access",
+  "extensions": {
+    "issues": [
+      {
+        "path": "minecraftUuid",
+        "message": "Expected a compact Java Edition UUID",
+        "code": "invalid_format"
+      }
+    ]
+  }
+}
+```
+
+`type`, `title`, and `status` are required. `detail`, `instance`, and `extensions` are included when relevant.
+
+## Problem catalog
+
+| Type | Status | Meaning |
+| --- | ---: | --- |
+| `urn:error:invalid-velocity-access-request` | 400 | Request JSON does not satisfy the shared Velocity contract |
+| `urn:error:unauthorized` | 401 | Velocity bearer credential is missing, invalid, or revoked |
+| `urn:error:expired-velocity-access-request` | 401 | Request timestamp is outside the accepted clock-skew window |
+| `urn:error:not-found` | 404 | Unknown application-owned API route |
+| `urn:error:method-not-allowed` | 405 | The endpoint does not support the requested HTTP method |
+| `urn:error:replayed-velocity-access-request` | 409 | Request ID was already processed |
+| `urn:error:unsupported-media-type` | 415 | The request does not use `application/json` |
+| `urn:error:service-unavailable` | 503 | A safe access decision could not be completed |
+
+A whitelist denial remains an HTTP `200` response containing `{ "allowed": false, "message": "..." }`. That response is a successfully evaluated authorization decision, not an HTTP error.
+
+Browser server actions continue to use redirects and accessible HTML messages. OAuth protocol responses under `/api/auth/*` are owned by NextAuth and follow that protocol's response behavior.