Error Codes
Prefix: application error codes use the EQ-INV- prefix (roughly EQ-INV-<HTTP><domain><seq>). Authentication errors surfaced by the auth layer use the EQ-USR- prefix. Every code maps to an HTTP status.
Every error response returns a machine-readable errorCode and a localized errorMessage. Validation failures add a list of field-level messages, and a validator extension may attach additional detail. The service also maps raw database errors: duplicate-key violations surface the relevant *_ALREADY_EXISTS code, and foreign-key violations surface the relevant *_NOT_FOUND code.
HTTP-Status Quick Reference
| Status | Meaning | Example codes |
|---|---|---|
| 400 | Bad request / validation | EQ-INV-4000001 (VALIDATION_ERROR), field validations |
| 401 | Unauthorized (auth) | EQ-INV-4010002, EQ-USR-4010001 |
| 403 | Forbidden / insufficient privilege | EQ-INV-4030001/2/3, EQ-USR-4030004/5 |
| 404 | Not found | EQ-INV-404xxxx |
| 409 | Conflict / already exists / state | EQ-INV-409xxxx |
| 422 | Business-rule / unprocessable | EQ-INV-422xxxx |
| 500 | Internal / DB / cache / event | EQ-INV-500xxxx |
| 503 | Service unavailable (EventBridge/external) | EQ-INV-5030001/2 |
Common / Cross-Cutting Errors
| Code | HTTP | When |
|---|---|---|
| EQ-INV-4000001 | 400 | Generic validation failure |
| EQ-INV-4220001 | 422 | Semantically invalid request |
| EQ-INV-4000002 | 400 | Malformed request |
| EQ-INV-4000003 | 400 | Bad sort value |
| EQ-INV-4030002 | 403 | Privilege check failed |
| EQ-INV-4090403 | 409 | Position version mismatch |
| EQ-INV-5000001 | 500 | Unhandled server error |
Revision History
2026-08-05 | AN – Page created and uploaded the contents