7. Error envelopes

7.1 Standard `ErrorResponse` (used by 400, 401, 429, 500)


{
  "timestamp": "2026-05-17T10:30:00.000",
  "status":    401,
  "error":     "Unauthorized",
  "message":   "Invalid or missing API key",
  "path":      "/api/v3/content/HO-XXXXXXXXXXXX/faq.json"
}

The brand property list endpoint also uses this envelope for its 404 (unknown or non-hospitality brandId):


{
  "timestamp": "2026-05-30T10:00:00.000",
  "status":    404,
  "error":     "Not Found",
  "message":   "Content not found with ID: HO-DOES-NOT-EXIST",
  "path":      "/api/v3/content/HO-DOES-NOT-EXIST/properties"
}

7.2 `FeedErrorResponse` (used by 404 and 413 on the feed endpoint)

Mirrors the standard envelope and adds nullable feed-specific fields. Exactly one of (entityCount, ceiling) or (bodyBytes, maxBytes) is populated on a 413; the other pair is absent. fallbackUrlPattern is always present on 413.

404 — entity not found


{
  "timestamp": "2026-05-17T12:34:56.789",
  "status":    404,
  "error":     "not-found",
  "message":   "No FAQ feed content for entityId=HO-DOES-NOT-EXIST",
  "path":      "/api/v3/content/HO-DOES-NOT-EXIST/faq.json",
  "entityId":  "HO-DOES-NOT-EXIST"
}

413 — entity-count ceiling breached


{
  "timestamp":          "2026-05-17T12:34:56.789",
  "status":             413,
  "error":              "payload-too-large",
  "message":            "FAQ JSON feed bulk response has 1247 entities, exceeding the ceiling of 1000.",
  "path":               "/api/v3/content/HO-XXXXXXXXXXXX/faq.json",
  "entityCount":        1247,
  "ceiling":            1000,
  "fallbackUrlPattern": "/api/v3/content/{entityId}/faq.json"
}

413 — body-byte ceiling breached


{
  "timestamp":          "2026-05-17T12:34:56.789",
  "status":             413,
  "error":              "payload-too-large",
  "message":            "FAQ JSON feed response serialized to 12582912 bytes, exceeding the 10485760-byte cap.",
  "path":               "/api/v3/content/HO-XXXXXXXXXXXX/faq.json",
  "bodyBytes":          12582912,
  "maxBytes":           10485760,
  "fallbackUrlPattern": "/api/v3/content/{entityId}/faq.json"
}

7.3 503 — feature flag disabled

Two-field envelope; does not match the standard error shape.


{
  "error":   "feature-disabled",
  "message": "The FAQ JSON feed is currently disabled."
}

503 is set by Bonafide operators via a live feature flag and may be flipped without redeploy. Implementations should treat it as a transient state and retry with the same exponential-backoff schedule used for 5xx generally.