Error Responses
Cleave returns HTTP errors before repository execution whenever a request fails preflight, authentication, authorization, query parsing, payload parsing, or request-size validation.
The HTTP status code is set on the response. The response body includes an errors array
with a title, numeric code, and human-readable details value.
Use the HTTP status code to identify the failure category and the response body for the details needed to correct the request.
{
"data": null,
"meta": {
"size": 0
},
"errors": [
{
"title": "No data",
"code": 204
},
{
"title": "Bad Request",
"code": 400,
"details": "Request path is malformed. Check prefix, collection and, or identity"
}
]
}
The details field is intended for client debugging and decision paths. Repository and
DBMS internals are intentionally hidden from clients by default, but the underlying reason
is logged for operators.
The first errors item currently carries a No data placeholder with code 204; clients
should use the HTTP status code and the later error item for failure handling.
Status Code Summary
| Code | Meaning in Cleave |
|---|---|
400 Bad Request | Malformed URI, invalid query parameter, invalid payload, invalid content length, invalid field name, unsupported JSON extension value, or a repository request rejected as invalid. |
401 Unauthorized | Missing or invalid bearer token, invalid JWT claims, or failed ACL authorization. |
403 Forbidden | Authenticated or configured request is understood, but access is forbidden, such as a forbidden collection or protected write field. |
405 Method Not Allowed | Method is known by Cleave but not valid for the resource shape. |
406 Not Acceptable | Required Accept, content language, or charset header is missing or does not match the configured value. |
413 Payload Too Large | Content-Length exceeds http.req_body_maxlength. |
414 URI Too Long | The request URI/cache key exceeds http.req_uri_maxlength. |
415 Unsupported Media Type | POST, PUT, or PATCH did not send Content-Type: application/vnd.api+json. |
500 Internal Server Error | Cleave server configuration prevents authorization, for example an invalid JWT secret. |
501 Not Implemented | Unknown HTTP method or repository adapter does not support a requested execution path. |
503 Service Unavailable | Client IP is outside service_available, or the repository/DBMS connection is unavailable. |
Preflight Errors
Preflight runs before method handlers and repository execution.
Malformed Resource
400 Bad Request is returned when Cleave cannot classify the URI as a collection or entity
resource:
{
"title": "Bad Request",
"code": 400,
"details": "Resource uri prefix, collection, id is indeterminate or malformed"
}
This usually means the path does not match interface.path_prefix, does not include a
collection name, includes an invalid entity identity, or otherwise cannot be parsed into a
known resource shape.
400 Bad Request is also returned when the path shape is known but malformed:
{
"title": "Bad Request",
"code": 400,
"details": "Request path is malformed. Check prefix, collection and, or identity"
}
Common cases:
- entity path has a trailing slash;
- entity ID is not 32 hexadecimal characters or a hyphenated UUID;
- collection path contains characters outside the accepted resource pattern.
Method Support
501 Not Implemented is returned when the HTTP method is not known by Cleave:
{
"title": "Not Implemented",
"code": 501,
"details": "Method not implemented"
}
405 Method Not Allowed is returned when the method is known but not valid for the
resource shape:
{
"title": "Method Not Allowed",
"code": 405,
"details": "Method not allowed"
}
Examples:
POST /api/0.0/person/018f...is not valid becausePOSTcreates through a collection;PATCH /api/0.0/personis not valid becausePATCHupdates a specific entity;PUT /api/0.0/personis not valid becausePUTupserts a specific entity.
See Request Requirements for the collection/entity method table.
Other method routing fallbacks may return 400 Bad Request with Method not supported or
Method not recognized, but normal requests should be rejected earlier by preflight.
URI Limit
414 URI Too Long is returned when the request URI/cache key exceeds
http.req_uri_maxlength:
{
"title": "URI Too Long",
"code": 414,
"details": "Length of URI exceeds the allowed maximum"
}
Reduce fields, filters, relationship parameters, or other query-string content.
Service Availability
503 Service Unavailable is returned when interface.service_available is populated and the
client IP does not match the allow-list:
{
"title": "Service Unavailable",
"code": 503,
"details": "Service not available for provided address"
}
Forwarded client IP headers are used only when forwarded-header support is enabled and the TCP peer is trusted.
Header Errors
Accept Header
GET requires:
Accept: application/vnd.api+json
If the header is missing or different, Cleave returns 406 Not Acceptable with a detail
such as:
{
"title": "Not Acceptable",
"code": 406,
"details": "accept header is missing"
}
or:
{
"title": "Not Acceptable",
"code": 406,
"details": "accept header is invalid"
}Content-Type Header
POST, PUT, and PATCH require:
Content-Type: application/vnd.api+json
If the header is missing or different, Cleave returns 415 Unsupported Media Type with a
detail such as:
{
"title": "Unsupported Media Type",
"code": 415,
"details": "content-type header is invalid"
}Content-Length Header
GET must not include request content. If it includes Content-Length, Cleave returns:
{
"title": "Bad Request",
"code": 400,
"details": "Request cannot have content"
}
POST, PUT, and PATCH must include Content-Length. If it is missing, Cleave returns:
{
"title": "Bad Request",
"code": 400,
"details": "Request must have content"
}
If Content-Length is malformed, Cleave returns:
{
"title": "Bad Request",
"code": 400,
"details": "Content-Length header is invalid"
}
If the value exceeds http.req_body_maxlength, Cleave returns:
{
"title": "Payload Too Large",
"code": 413,
"details": "Payload to large"
}Content Language And Charset Headers
Content language and charset checks are disabled when the corresponding configuration value is empty. When configured, the request header must be present and must exactly match the configured value.
| Configuration | Header | Error |
|---|---|---|
interface.language.content_language | Content-Language | 406 Not Acceptable |
interface.language.accept_charset | Accept-Charset | 406 Not Acceptable |
interface.language.content_charset | content-charset | 406 Not Acceptable |
Details follow the standard header pattern: the header is missing or invalid.
Accept-Language is advisory until Cleave has localized response bodies. Clients should
not treat it as a required header for error-handling decisions.
Authentication And Authorization Errors
When authentication is enabled, missing or malformed bearer tokens return
401 Unauthorized.
Common details include:
| Details | Why it occurs |
|---|---|
authorization header is missing | No Authorization header was supplied. |
authorization header is invalid | The header value could not be read as a valid header string. |
Request is unauthorized. Bearer token is required | The header does not start with Bearer or has no token value. |
Request is unauthorized. Bearer token fails verification. | Signature verification failed. |
Authorization secret is invalid | Cleave could not create the HMAC key from auth.secret; currently returned as 500 Internal Server Error. |
JWT registered-claim failures also return 401 Unauthorized:
| Details | Why it occurs |
|---|---|
Request is unauthorized. Bearer token needs iat | iat is missing. |
Request is unauthorized. Bearer token iat is malformed | iat is not a numeric date. |
Request is unauthorized. Bearer token needs exp | exp is required and missing. |
Request is unauthorized. Bearer token exp is malformed | exp is not a numeric date. |
Request is unauthorized. Bearer token has expired | exp is in the past, or older issued-at compatibility rules reject the token. |
Request is unauthorized. Bearer token needs nbf | nbf is required and missing. |
Request is unauthorized. Bearer token nbf is malformed | nbf is not a numeric date. |
Request is unauthorized. Bearer token is not valid yet | nbf is later than the current time after clock-skew handling. |
Request is unauthorized. Bearer token issuer is malformed | iss is required by configuration but not a string. |
Request is unauthorized. Bearer token issuer is invalid | iss does not match auth.issuer. |
Request is unauthorized. Bearer token audience is invalid | aud does not match auth.audience. |
Cleave access-claim and ACL failures return 401 Unauthorized:
| Details | Why it occurs |
|---|---|
Request is unauthorized. Bearer token needs uid | User-based access requires uid. |
Request is unauthorized. Bearer token uid is malformed | uid is not a string. |
Request is unauthorized. Bearer token needs gid | Group-based access requires gid. |
Request is unauthorized. Bearer token gid is malformed | gid is not a string. |
Forbidden resources and fields return 403 Forbidden:
| Details | Why it occurs |
|---|---|
Collection is forbidden | The collection is listed in interface.collections.forbidden. |
Specifying <field> is forbidden | The client supplied a protected field in a write payload. |
Query Parameter Errors
Query parsing failures return 400 Bad Request.
| Details | Why it occurs |
|---|---|
The query parameter is missing and invalid | A query parameter has an empty value. |
The query <name> is invalid | The query key is not recognized. |
The query parameter for fields must contain 'id' or '*' | fields does not include id or *. |
The query parameter for fields is invalid | fields includes invalid characters. |
The query parameter for page[$skip] is invalid | page[$skip] is not numeric or is negative. |
The query parameter for page[$limit] is invalid | page[$limit] is not numeric or is less than one. |
The query parameter for page[$limit] exceeds the permitted size | page[$limit] exceeds interface.paging.limit_max. |
The query parameter for filter is invalid | The filter[...] key is malformed. |
The query parameter for filter is empty and invalid | The filter field name is empty. |
Field name contains invalid chars | A field name fails Cleave's field-name lint. |
The query parameter for join is invalid | The relation[...] key is malformed. |
The query parameter for join is empty and invalid | The relation key is empty. |
The query parameter cannot be bound | A value-binding path received an operator/value shape that cannot be parameterized. |
The query parameter missing double quotes is invalid | A quoted filter value starts with a quote but does not close correctly. |
The query parameter unsigned integer is too large for Postgres | A bound unsigned integer cannot fit in the PostgreSQL integer representation used by the adapter. |
Filter operator errors also return 400 Bad Request:
| Details |
|---|
The query parameter for $eq[] is invalid |
The query parameter for $neq[] is invalid |
The query parameter for $is[] is invalid |
The query parameter for $isnt[] is invalid |
The query parameter for $gt[] is invalid |
The query parameter for $gte[] is invalid |
The query parameter for $lt[] is invalid |
The query parameter for $lte[] is invalid |
The query parameter for $bin[] is invalid |
The query parameter for $uuid[] is invalid |
Payload Errors
Payload parsing failures return 400 Bad Request unless a protected field is supplied,
which returns 403 Forbidden.
| Details | Why it occurs |
|---|---|
The body is invalid | The request body cannot be collected or decoded as UTF-8. |
The json body is invalid | The body is not valid JSON. |
Type is needed in the payload | POST payload does not include data.type. |
Type is needed in the json payload | PUT or PATCH payload does not include data.type. |
Type in payload must match collection name in the URI | POST data.type does not match the collection path. |
Type must match collection name in the URI | PUT or PATCH data.type does not match the collection path. |
Ext type is unknown/unsupported | meta.ext is a string but not none, segregated, or collated. |
Ext type is missing/invalid | meta.ext exists but is not a string. |
Write acknowledgement must be true/false | A write acknowledgement value is not a boolean. |
Write acknowledgement aliases conflict | More than one acknowledgement alias was supplied with different boolean values. |
Array type in payload not currently permitted | Plain payload mode received an array attribute value. |
Object type in payload not currently permitted | Plain payload mode received an object attribute value. |
Array type not currently permitted | Segregated payload mode received an unsupported array attribute value. |
Array type in payload not currently supported | Collated payload mode received an unsupported array attribute value. |
Object type in payload not currently supported | Collated payload mode received an unsupported object attribute value. |
Payload is invalid | Segregated payload mode received an empty object or a non-reserved object key where a reserved key was required. |
Reserved payload value errors also return 400 Bad Request:
| Details | Why it occurs |
|---|---|
Random value is invalid | A random-value operator received an invalid length or number. |
Randomizing key ($rnd:??) in payload not recognized | The random-value subtype is unsupported. |
Reserved word in payload not recognized | The reserved payload operator is unsupported. |
Reserved word 'uuid' in payload is invalid | A collated UUID value is not a supported UUID shape. |
'Uuid' in payload is invalid type | A segregated UUID value is not a string. |
'Uuid' in payload is invalid length | A segregated UUID value is not 32 characters. |
Datetime with local zones are not supported. Use an offset | A local-zone datetime operator was used. |
Unix datetime is malformed | Unix timestamp datetime conversion failed. |
Rfc2822 datetime is malformed | RFC 2822 datetime parsing failed. |
Rfc3339 datetime is malformed. | RFC 3339 datetime parsing failed. |
Iso8601 datetime is malformed | ISO 8601 datetime parsing failed. |
Rfc2822 datetime w offset is malformed | RFC 2822 offset datetime parsing failed. |
Rfc3339 datetime w offset is malformed | RFC 3339 offset datetime parsing failed. |
Iso8601 datetime w offset is malformed> | ISO 8601 offset datetime parsing failed. |
Datetime key ($dt:??) in payload not recognized | The datetime subtype is unsupported. |
Timedate key ($dto:??) in payload not recognized | The offset datetime subtype is unsupported. |
Rfc2822 date is malformed | RFC 2822 date parsing failed. |
Rfc3339 date is malformed | RFC 3339 date parsing failed. |
Iso8601 date is malformed | ISO 8601 date parsing failed. |
Date key (d:??)in payload not recognized | The date subtype is unsupported. |
Unix time is malformed | Unix timestamp time conversion failed. |
Rfc2822 time is malformed | RFC 2822 time parsing failed. |
Rfc3339 time is malformed | RFC 3339 time parsing failed. |
Iso8601 time is malformed | ISO 8601 time parsing failed. |
Time key ($t:??) in payload not recognized | The time subtype is unsupported. |
Repository Errors
Cleave hides repository-specific error details from clients by default.
When the repository connection is unavailable, Cleave returns:
{
"title": "Service Unavailable",
"code": 503,
"details": "Repo/DBMS is not available"
}
When the repository rejects a generated request, Cleave normally returns:
{
"title": "Bad Request",
"code": 400,
"details": "Repository request is invalid"
}
For unknown repository failures, Cleave may return:
{
"title": "Bad Request",
"code": 400,
"details": "Error issued during query"
}
If interface.errors.expose_repository_codes = true, clients may receive a generic repository
code instead:
{
"title": "Bad Request",
"code": 400,
"details": "Repo/DBMS Error: Code <code>"
}
The detailed DBMS error is sent to logging/syslog for operators. Clients should not depend on repository-specific text for control flow.
If a selected repository adapter cannot execute a parameterized statement path, Cleave
returns 501 Not Implemented with:
{
"title": "Not Implemented",
"code": 501,
"details": "Repository driver does not support parameterized statements"
}Logging Behavior
Errors are written to the configured logging path. Client responses are intentionally structured and limited, while operational logs can contain the detailed reason needed to diagnose repository failures, authorization failures, malformed requests, and parser failures.
Because logs can contain sensitive request and repository context, production deployments should protect logging destinations and choose the logging level deliberately. See Logging and Metrics.