Idempotent Endpoint

Problem

Build a POST endpoint that safely handles duplicate requests using idempotency keys.

Background

In production systems, network failures and client retries mean the same request can arrive multiple times. An idempotent endpoint ensures that processing a request multiple times produces the same result as processing it once — no duplicate records, no double charges, no inconsistent state.

This is a fundamental reliability pattern used in payment systems, order processing, and any operation with real-world side effects.

Requirements

• Implement POST /orders that creates an order and stores it in the database
• Accept an Idempotency-Key header on every request
• If the same idempotency key is sent again, return the original response without creating a duplicate order
• Handle concurrent duplicate requests safely — two identical requests arriving at the same time must not create two orders
• Reject requests that are missing the Idempotency-Key header with 400

Your Server

• Start an HTTP server on the port specified by the PORT environment variable (default: 3000)
• A PostgreSQL database is available at the DATABASE_URL environment variable
• You are responsible for creating any tables you need (run your schema setup on startup)

API Contract

`GET /health`

Health check endpoint. Return 200 when your server is ready.

• Response: 200 { "status": "ok" }

`POST /orders`

Create a new order (idempotent).

Request:

• Header: Idempotency-Key: (required)
• Body: { "item": "string", "quantity": number }

Response (new order):

• Status: 201
• Body: { "id": "", "item": "string", "quantity": number }

Response (duplicate request):

• Status: 200
• Body: { "id": "", "item": "string", "quantity": number } (same ID as original)

Response (missing idempotency key):

• Status: 400
• Body: { "error": "Idempotency-Key header is required" }