docs: define time-unit invalid bound error contract

documentation/CHANGELOG.md

@@ -13,6 +13,7 @@
 - Locality age validation now enforces required age-basis rules against the active dating method while tolerating preserved values from non-active methods.
 - Locality -> Species (`/locality/:id?tab=2`) edit-mode minus action now consistently targets the clicked species row when table ordering differs from source data, preventing incorrect red highlight on other rows.
 - Added Cypress regression coverage in `cypress/e2e/locality.cy.js` to verify row-action remove state is applied only to the clicked species row.
+- Time Unit write failures with non-existent `up_bnd`/`low_bnd` now return structured `403` validation payloads (including Prisma FK guardrail mapping) instead of internal `500` errors.
 
 ### Added
 - Species table Genus and Species filters now also match synonym names (syn_genus_name and syn_species_name) returned with each species record.

documentation/api/time-units.md

@@ -33,6 +33,37 @@ Only the relevant editable fields are shown above; the full payload mirrors the
 
 - `403 Forbidden` – Standard validation errors. Response matches the existing validator error array or cascade error object.
 
+#### Missing Time Bound reference (guarded non-500 response)
+
+When `up_bnd` and/or `low_bnd` references do not exist, the API now returns a deterministic client error instead of an internal server error.
+
+- Status: `403 Forbidden`
+- Response body example (single invalid bound):
+
+```json
+[
+  {
+    "name": "Lower Bound",
+    "error": "Lower bound with ID 30000 does not exist"
+  }
+]
+```
+
+- Response body example (both invalid):
+
+```json
+[
+  {
+    "name": "Upper Bound",
+    "error": "Upper bound with ID 40000 does not exist"
+  },
+  {
+    "name": "Lower Bound",
+    "error": "Lower bound with ID 30000 does not exist"
+  }
+]
+```
+
 ### Duplicate Name Response
 
 - `409 Conflict` – A time unit with the same normalized name already exists.

documentation/entities/time_unit.md

@@ -15,6 +15,28 @@ The components that are used to change the upper or lower time bounds are `TimeB
 
 After the time unit is created, its ID (`tu_name`) is set to be the same as its name, but lowercase (for example, a time unit with the name "Abdounian" has the id "abdounian"). Because of this, changing an existing time unit's name causes a foreign key error in the database because the "now_time_unit" and "now_tau" tables are connected by it. When editing a time unit, the name field is currently disabled to not allow this error to happen.
 
+
+## Validation behavior for missing bounds
+
+For `PUT /time-unit`, `up_bnd` and `low_bnd` are validated against existing Time Bound records before write operations. If one or both referenced bounds are missing, the request is rejected with `403` and a structured validation array instead of returning `500`.
+
+Example response:
+
+```json
+[
+  {
+    "name": "Upper Bound",
+    "error": "Upper bound with ID 40000 does not exist"
+  },
+  {
+    "name": "Lower Bound",
+    "error": "Lower bound with ID 30000 does not exist"
+  }
+]
+```
+
+This contract is intentionally consumable by frontend validation/error-notification logic.
+
 ## Problems:
 
 At the moment it seems that Time Units get info about their updates from wrong places. Old PHP-version displays differring data on updates tab. It seems (I might be wrong about this) that PHP-version bases the info on the table now_time_update and the new one on the table now_tau. Prisma doesn't seem to handle the query if based on now_time_update with current schema, but the change should be doable with Prisma's rawSQL.