📝 docs: second error format — 412 + bare Spring validation array #123

Merged
mat merged 1 commit from docs/412-error-format into main 2026-10-11 11:06:51 +00:00
Owner

Summary

Document the API's second error format in the field notes (roadmap §2.3, issue #68):

 docs/energy.comwatt.com/README.md — Error / status-code conventions
   RFC-7807 problem+json shape (unchanged)
+  second format: 412 + bare JSON array of Spring validation errors
+    example, observed endpoints, dict-assumption hazard
 Typical codes observed
+  412 — bare array, not problem+json

 docs/energy.comwatt.com/devices.md
   gateways/{id}/network one-off mention
+    → cross-link to the conventions section

Client-side handling of the array shape (_response_detail / _api_error) stays out of scope — tracked in #101.

Closes #68.

Evidence

  • Before: the 412 + bare-array format appears only as a one-off note in devices.md; the conventions section lists no 412 and no second shape.
    After: README.md (docs) documents the format with the observed example, the three endpoints (users/{id}/refreshtoken, gateways/{id}/network, companies/installation-company-by-installer-email), the code/codes field, the list-not-dict hazard, and adds 412 to typical codes; devices.md links to it.

Docs-only change, no code touched. Test suite: 139 passed (unchanged baseline).

Merge Danger

Door: two-way (docs-only, trivially revertible)

Blast Radius: none — documentation only.

## Summary Document the API's second error format in the field notes (roadmap §2.3, issue #68): ```diff docs/energy.comwatt.com/README.md — Error / status-code conventions RFC-7807 problem+json shape (unchanged) + second format: 412 + bare JSON array of Spring validation errors + example, observed endpoints, dict-assumption hazard Typical codes observed + 412 — bare array, not problem+json docs/energy.comwatt.com/devices.md gateways/{id}/network one-off mention + → cross-link to the conventions section ``` Client-side handling of the array shape (`_response_detail` / `_api_error`) stays out of scope — tracked in #101. Closes #68. ## Evidence - **Before:** the 412 + bare-array format appears only as a one-off note in `devices.md`; the conventions section lists no `412` and no second shape. **After:** `README.md` (docs) documents the format with the observed example, the three endpoints (`users/{id}/refreshtoken`, `gateways/{id}/network`, `companies/installation-company-by-installer-email`), the `code`/`codes` field, the list-not-dict hazard, and adds `412` to typical codes; `devices.md` links to it. Docs-only change, no code touched. Test suite: 139 passed (unchanged baseline). ## Merge Danger **Door:** two-way (docs-only, trivially revertible) **Blast Radius:** none — documentation only.
📝 docs: second error format — 412 + bare Spring validation array
All checks were successful
Tests / forgejo-pytest (pull_request) Successful in 41s
Tests / forgejo-pytest (push) Successful in 42s
50517077fa
mat changed title from WIP: 📝 docs: second error format — 412 + bare Spring validation array to 📝 docs: second error format — 412 + bare Spring validation array 2026-10-11 11:06:48 +00:00
mat merged commit de21fee1cb into main 2026-10-11 11:06:51 +00:00
mat deleted branch docs/412-error-format 2026-10-11 11:06:51 +00:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
mat/python-comwatt-client!123
No description provided.