11. API & Protocols/Diagnostics
Error Codes & Diagnostics
The GN-Apex Control Plane adheres to strict JSON error envelopes. Applications should parse the errorCode field for programmatic branching rather than parsing the human-readable message.
PREDICTABLE FAULT TOLERANCE
JSON
Standardized Fault Envelope
“Catch and handle constraints, authentication rejections, and database collisions programmatically.”
SRE Diagnostics
Standard Error Envelope
All non-2xx responses return a structured fault object:
json
| 1 | { |
| 2 | "statusCode": 409, |
| 3 | "errorCode": "RECORD_COLLISION", |
| 4 | "message": "Collision error: A record with this email already exists.", |
| 5 | "timestamp": "2026-05-12T14:30:00.000Z" |
| 6 | } |
Error Code Dictionary
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| RECORD_COLLISION | HTTP 409 | Optional | Database Unique Constraint Violation. You are trying to insert a value (like an email or slug) that already exists. |
| FOREIGN_KEY_VIOLATION | HTTP 400 | Optional | You are attempting to link a record to a parent ID that does not exist in the database. |
| RECORD_NOT_FOUND | HTTP 404 | Optional | The requested entity ID was not found. |
| DB_VALIDATION_ERROR | HTTP 400 | Optional | Data structure rejection. Typically implies a missing required schema field. |
| CIRCUIT_OPEN | HTTP 503 | Optional | The upstream edge gateway is temporarily paused due to repeated failure thresholds. Try again later. |
Validation Handling
Validation Pipeline Array
If a payload fails initial DTO validation (e.g. malformed email or missing string), the API returns a
400 Bad Request where the message field is an array of strings detailing every invalid property.