Versioned REST APIs & Secure Access

POST /v2/leads            Idempotency-Key: 7c9e-4411-a2   → 201 Created  lead LEAD-10236
POST /v2/leads  (retry)   Idempotency-Key: 7c9e-4411-a2   → 200 OK       same body
                                                            Idempotency-Replayed: true

PUT /v2/listings/LST-2041  If-Match: "v17"                 → 409 Conflict (no silent overwrite)
                           errorCode: VERSION_CONFLICT      currentVersion: "v19"

Concurrent updates require ETag / If-Match (or equivalent version token) and return an explicit conflict. Write APIs additionally enforce permissions and business invariants server-side — a valid token alone never bypasses RBAC.

{
  "type": "https://api.almanara.ae/problems/duplicate-lead",
  "title": "Duplicate lead",
  "status": 409,
  "errorCode": "LEAD_DUPLICATE",
  "detail": "A lead for this contact already exists in the last 30 days.",
  "violations": [
    { "field": "phone", "code": "DUPLICATE_MATCH", "ref": "LEAD-10188" }
  ],
  "correlationId": "c0a8-17ju-2026-8842",
  "retryable": false,
  "supportRef": "SUP-4471"
}

One envelope for every API error: stable error code, human-safe message, field violations, correlation ID, retryability flag and support reference. No stack traces or sensitive payloads are ever exposed (§10.3). Correlation IDs join the Audit Explorer trail.