---
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)