Documentation

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

CodeMeaning in Cleave
400 Bad RequestMalformed URI, invalid query parameter, invalid payload, invalid content length, invalid field name, unsupported JSON extension value, or a repository request rejected as invalid.
401 UnauthorizedMissing or invalid bearer token, invalid JWT claims, or failed ACL authorization.
403 ForbiddenAuthenticated or configured request is understood, but access is forbidden, such as a forbidden collection or protected write field.
405 Method Not AllowedMethod is known by Cleave but not valid for the resource shape.
406 Not AcceptableRequired Accept, content language, or charset header is missing or does not match the configured value.
413 Payload Too LargeContent-Length exceeds http.req_body_maxlength.
414 URI Too LongThe request URI/cache key exceeds http.req_uri_maxlength.
415 Unsupported Media TypePOST, PUT, or PATCH did not send Content-Type: application/vnd.api+json.
500 Internal Server ErrorCleave server configuration prevents authorization, for example an invalid JWT secret.
501 Not ImplementedUnknown HTTP method or repository adapter does not support a requested execution path.
503 Service UnavailableClient 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 because POST creates through a collection;
  • PATCH /api/0.0/person is not valid because PATCH updates a specific entity;
  • PUT /api/0.0/person is not valid because PUT upserts 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.

ConfigurationHeaderError
interface.language.content_languageContent-Language406 Not Acceptable
interface.language.accept_charsetAccept-Charset406 Not Acceptable
interface.language.content_charsetcontent-charset406 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:

DetailsWhy it occurs
authorization header is missingNo Authorization header was supplied.
authorization header is invalidThe header value could not be read as a valid header string.
Request is unauthorized. Bearer token is requiredThe header does not start with Bearer or has no token value.
Request is unauthorized. Bearer token fails verification.Signature verification failed.
Authorization secret is invalidCleave could not create the HMAC key from auth.secret; currently returned as 500 Internal Server Error.

JWT registered-claim failures also return 401 Unauthorized:

DetailsWhy it occurs
Request is unauthorized. Bearer token needs iatiat is missing.
Request is unauthorized. Bearer token iat is malformediat is not a numeric date.
Request is unauthorized. Bearer token needs expexp is required and missing.
Request is unauthorized. Bearer token exp is malformedexp is not a numeric date.
Request is unauthorized. Bearer token has expiredexp is in the past, or older issued-at compatibility rules reject the token.
Request is unauthorized. Bearer token needs nbfnbf is required and missing.
Request is unauthorized. Bearer token nbf is malformednbf is not a numeric date.
Request is unauthorized. Bearer token is not valid yetnbf is later than the current time after clock-skew handling.
Request is unauthorized. Bearer token issuer is malformediss is required by configuration but not a string.
Request is unauthorized. Bearer token issuer is invalidiss does not match auth.issuer.
Request is unauthorized. Bearer token audience is invalidaud does not match auth.audience.

Cleave access-claim and ACL failures return 401 Unauthorized:

DetailsWhy it occurs
Request is unauthorized. Bearer token needs uidUser-based access requires uid.
Request is unauthorized. Bearer token uid is malformeduid is not a string.
Request is unauthorized. Bearer token needs gidGroup-based access requires gid.
Request is unauthorized. Bearer token gid is malformedgid is not a string.

Forbidden resources and fields return 403 Forbidden:

DetailsWhy it occurs
Collection is forbiddenThe collection is listed in interface.collections.forbidden.
Specifying <field> is forbiddenThe client supplied a protected field in a write payload.

Query Parameter Errors

Query parsing failures return 400 Bad Request.

DetailsWhy it occurs
The query parameter is missing and invalidA query parameter has an empty value.
The query <name> is invalidThe 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 invalidfields includes invalid characters.
The query parameter for page[$skip] is invalidpage[$skip] is not numeric or is negative.
The query parameter for page[$limit] is invalidpage[$limit] is not numeric or is less than one.
The query parameter for page[$limit] exceeds the permitted sizepage[$limit] exceeds interface.paging.limit_max.
The query parameter for filter is invalidThe filter[...] key is malformed.
The query parameter for filter is empty and invalidThe filter field name is empty.
Field name contains invalid charsA field name fails Cleave's field-name lint.
The query parameter for join is invalidThe relation[...] key is malformed.
The query parameter for join is empty and invalidThe relation key is empty.
The query parameter cannot be boundA value-binding path received an operator/value shape that cannot be parameterized.
The query parameter missing double quotes is invalidA quoted filter value starts with a quote but does not close correctly.
The query parameter unsigned integer is too large for PostgresA 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.

DetailsWhy it occurs
The body is invalidThe request body cannot be collected or decoded as UTF-8.
The json body is invalidThe body is not valid JSON.
Type is needed in the payloadPOST payload does not include data.type.
Type is needed in the json payloadPUT or PATCH payload does not include data.type.
Type in payload must match collection name in the URIPOST data.type does not match the collection path.
Type must match collection name in the URIPUT or PATCH data.type does not match the collection path.
Ext type is unknown/unsupportedmeta.ext is a string but not none, segregated, or collated.
Ext type is missing/invalidmeta.ext exists but is not a string.
Write acknowledgement must be true/falseA write acknowledgement value is not a boolean.
Write acknowledgement aliases conflictMore than one acknowledgement alias was supplied with different boolean values.
Array type in payload not currently permittedPlain payload mode received an array attribute value.
Object type in payload not currently permittedPlain payload mode received an object attribute value.
Array type not currently permittedSegregated payload mode received an unsupported array attribute value.
Array type in payload not currently supportedCollated payload mode received an unsupported array attribute value.
Object type in payload not currently supportedCollated payload mode received an unsupported object attribute value.
Payload is invalidSegregated 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:

DetailsWhy it occurs
Random value is invalidA random-value operator received an invalid length or number.
Randomizing key ($rnd:??) in payload not recognizedThe random-value subtype is unsupported.
Reserved word in payload not recognizedThe reserved payload operator is unsupported.
Reserved word 'uuid' in payload is invalidA collated UUID value is not a supported UUID shape.
'Uuid' in payload is invalid typeA segregated UUID value is not a string.
'Uuid' in payload is invalid lengthA segregated UUID value is not 32 characters.
Datetime with local zones are not supported. Use an offsetA local-zone datetime operator was used.
Unix datetime is malformedUnix timestamp datetime conversion failed.
Rfc2822 datetime is malformedRFC 2822 datetime parsing failed.
Rfc3339 datetime is malformed.RFC 3339 datetime parsing failed.
Iso8601 datetime is malformedISO 8601 datetime parsing failed.
Rfc2822 datetime w offset is malformedRFC 2822 offset datetime parsing failed.
Rfc3339 datetime w offset is malformedRFC 3339 offset datetime parsing failed.
Iso8601 datetime w offset is malformed>ISO 8601 offset datetime parsing failed.
Datetime key ($dt:??) in payload not recognizedThe datetime subtype is unsupported.
Timedate key ($dto:??) in payload not recognizedThe offset datetime subtype is unsupported.
Rfc2822 date is malformedRFC 2822 date parsing failed.
Rfc3339 date is malformedRFC 3339 date parsing failed.
Iso8601 date is malformedISO 8601 date parsing failed.
Date key (d:??)in payload not recognizedThe date subtype is unsupported.
Unix time is malformedUnix timestamp time conversion failed.
Rfc2822 time is malformedRFC 2822 time parsing failed.
Rfc3339 time is malformedRFC 3339 time parsing failed.
Iso8601 time is malformedISO 8601 time parsing failed.
Time key ($t:??) in payload not recognizedThe 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.