feat(api): standardize V3 error status codes and documentation

- Updated V3 CRUD routers to return 400 Bad Request for database schema
  errors (unknown columns) across all list and search endpoints.
- Fixed serialization issue in nested patch endpoint.
- Overhauled Section 7 of Frontend Integration Guide to document HTTP
  status code mappings for common error categories.
This commit is contained in:
Scott Idem
2026-01-29 18:18:04 -05:00
parent b862d59e65
commit 5d91c05925
3 changed files with 22 additions and 6 deletions

View File

@@ -132,11 +132,18 @@ V3 uses a **String-Only ID Vision**. The frontend NEVER handles or stores databa
V3 returns machine-readable error objects in `meta.details` for failures.
**Common Categories:**
- `database_duplicate`: Non-unique value (Code 1062).
- `database_constraint`: Foreign key violation (Codes 1451, 1452).
- `database_schema`: Invalid column name (Codes 1054, 1146).
- `validation`: Pydantic validation failed (Check `details` for field-specific errors).
### HTTP Status Codes
- **`400 Bad Request`**: Used for client-driven errors including invalid search fields, validation failures, and constraint violations.
- **`403 Forbidden`**: Missing or invalid API Key / Account Context.
- **`404 Not Found`**: Object ID does not exist.
- **`500 Internal Server Error`**: Unexpected server crash or database connection failure.
### Common Error Categories
Found in `meta.details.category`:
- `database_duplicate`: Non-unique value (Code 1062). -> **400**
- `database_constraint`: Foreign key violation (Codes 1451, 1452). -> **400**
- `database_schema`: Invalid column name or missing field in the requested `view` (Codes 1054, 1146). -> **400**
- `validation`: Pydantic validation failed (Check `details` for field-specific errors). -> **400**
---