JQL Fundamentals
Errors
JQL error envelopes, common status codes, validation failures, auth errors, and debug options.
JQL normalizes most processor exceptions into the response error contract. In debug mode, the server may re-raise underlying exceptions instead.
Error shape
Errors are built from an error object with these fields:
{
"error_message": "Record not found",
"error_code": "404",
"error_payload": {},
"status_code": 404
}In a failed HTTP response this may appear inside the framework error response; recoverable processor errors can also be returned in __errors__.
Common failures
- Missing
__meta__.intentor__meta__.namespace: validation error from the base processor. - Not authenticated: anonymous user rejected for private schemes.
- Not authorized: permission failure for
namespace:intentor permission-scoped queryset. - Record not found:
retrieveOne,update,deleteOne, or consequenceuniqueObjectdid not match an accessible row. - Validation error: serializer, model clean, type conversion, choice, required field, or mutation validation failed.
- Integrity error: duplicate or protected relational data blocked a mutation.
Debug mode
Set __meta__.debug: true to let exceptions surface during development. Production should rely on the structured error envelope.
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "system.User",
5 "intent": "retrieveOne",
6 "authenticationClass": "jwt",
7 "debug": true,
8 "uniqueObject": {
9 "id": -1
10 }
11 },
12 "id": null,
13 "email": null
14}Auth-specific errors
Authentication intents such as authenticate, refreshToken, verifyAuthentication, password reset, and registration flows can be exempt from the normal authentication class, but they still return validation or account-state errors through the same structure.
See jql overview, intents, and /developer/authentication-classes.