# Spec Delta

## Purpose

Make failures predictable and safe for API consumers while retaining enough correlated diagnostic information for operators.

## ADDED Requirements

### Requirement: Request correlation
The API SHALL generate a server-controlled request ID before request parsing and include it in `X-Request-Id`, JSON response metadata, and request/failure logs. Incoming request IDs SHALL NOT replace the server-controlled identifier.

#### Scenario: Parser failure correlation
- **WHEN** malformed JSON is rejected before routing
- **THEN** the 400 response header and error envelope contain the same request ID as the failure log

### Requirement: Uniform failure paths
Application, validation, parsing, authentication, authorization, rate-limit, and unmatched API-route failures SHALL follow the response contract. Unknown API routes SHALL return 404 `ROUTE_NOT_FOUND`. Rate-limit responses SHALL preserve Retry-After. Oversized JSON bodies SHALL return 413 `PAYLOAD_TOO_LARGE` in the error envelope.

#### Scenario: Unmatched API route
- **WHEN** a client calls an unregistered `/api/v1` path
- **THEN** the response is a JSON 404 error envelope rather than the framework HTML response

#### Scenario: Repeated login attempts
- **WHEN** login requests exceed the existing rate limit
- **THEN** the response is 429 with `RATE_LIMIT_EXCEEDED`, a safe Indonesian message, and Retry-After

### Requirement: Safe unexpected failures
Unknown failures SHALL return 500 `INTERNAL_ERROR` with a generic Indonesian message. Responses in every environment SHALL omit stack traces, raw database messages, internal paths, credentials, and tokens. Logs SHALL retain request-correlated diagnostics while excluding passwords, tokens, cookie contents, and unredacted request bodies.

#### Scenario: Database exception containing private text
- **WHEN** an unexpected database exception includes internal connection information
- **THEN** the client receives only a safe generic error and request ID
- **AND** diagnostic logging does not expose credentials

### Requirement: Contextual expected failures
Known domain errors SHALL map to stable public codes independently of message text. Persistence conflicts SHALL be translated using operation context. A missing requested resource SHALL yield 404; a conflicting current state SHALL yield 409. A database programming error SHALL NOT be presented as user input failure.

#### Scenario: Insufficient stock
- **WHEN** a stock operation cannot satisfy the requested quantity
- **THEN** the response is 409 `INSUFFICIENT_STOCK` with a safe Indonesian explanation

#### Scenario: Missing related data
- **WHEN** an operation encounters a missing referenced record rather than a missing requested target
- **THEN** its documented validation or conflict response is used rather than indiscriminately reporting target-not-found

### Requirement: Response completion safety
Failures occurring after response headers have been sent SHALL NOT cause a second JSON response attempt. Request handling SHALL record the failure and allow the connection or stream to terminate through the server's error mechanism.

#### Scenario: Failure during streaming
- **WHEN** a response stream fails after headers are sent
- **THEN** the server logs the correlated failure and does not append an error envelope to the stream