46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
---
|
|
type: User Story
|
|
title: Receive standardized API errors
|
|
description: Application-owned HTTP APIs expose RFC 9457 Problem Details matching game-ingest-server conventions.
|
|
tags: [api, errors, rfc9457, contracts]
|
|
timestamp: 2026-08-01T18:43:58Z
|
|
story_id: US-014
|
|
status: verified
|
|
---
|
|
|
|
# User Story
|
|
|
|
As an API consumer, I want errors returned as standardized Problem Details, so that failures can be handled consistently across game services.
|
|
|
|
# Acceptance Criteria
|
|
|
|
- [x] Error responses use `application/problem+json`.
|
|
- [x] Responses require `type`, `title`, and `status` and optionally include `detail`, `instance`, and `extensions`.
|
|
- [x] Invalid Velocity payloads include machine-readable Zod issues under `extensions.issues`.
|
|
- [x] Missing credentials, expired requests, replays, unsupported media, unsupported methods, unknown routes, and service failures have stable `urn:error:*` types.
|
|
- [x] Unexpected application-owned Velocity errors are converted to safe `503` problems without internal details.
|
|
- [x] A normal whitelist denial remains a successful `200` authorization decision.
|
|
- [x] Browser form redirects remain accessible HTML flows and OAuth protocol responses remain owned by NextAuth.
|
|
|
|
# Implementation
|
|
|
|
- [`packages/contracts/src/index.ts`](../packages/contracts/src/index.ts)
|
|
- [`apps/web/src/lib/problem-response.ts`](../apps/web/src/lib/problem-response.ts)
|
|
- [`apps/web/src/app/api/velocity/access/route.ts`](../apps/web/src/app/api/velocity/access/route.ts)
|
|
- [`docs/api-errors.md`](../docs/api-errors.md)
|
|
|
|
# Validation
|
|
|
|
- [`packages/contracts/test/problem-details.test.ts`](../packages/contracts/test/problem-details.test.ts)
|
|
- [`apps/web/src/app/api/velocity/access/route.test.ts`](../apps/web/src/app/api/velocity/access/route.test.ts)
|
|
- Unknown-route and response-helper tests in the web workspace.
|
|
|
|
# Related Stories
|
|
|
|
- [Velocity game admission](us-009-velocity-admission.md)
|
|
- [Deploy and operate securely](us-015-platform-operations.md)
|
|
|
|
# Citations
|
|
|
|
[1] [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457)
|