error-reference.adoc

REST API Gateway Error Reference

The REST API Gateway returns error responses conforming to RFC 9457 — Problem Details for HTTP APIs.

1. Response Format

Every error response uses content type application/problem+json:

{
  "type": "https://github.com/cuioss/nifi-extensions/blob/main/doc/reference/error-reference.adoc#unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or malformed Authorization header"
}

The type field links to the matching anchored section of this documentation page (e.g. #unauthorized). The fragments below match the anchors emitted by the ProblemDetail record (ProblemDetail.TYPE_*).

2. Error Types

Status	Title	When Returned	Example detail value
400	Bad Request	Input sanitization failed: malformed path, query parameters, or headers detected by cui-http security pipelines	Request rejected: Known attack signature detected
401	Unauthorized	Missing or invalid Bearer token. Includes WWW-Authenticate: Bearer header per RFC 6750.	Missing or malformed Authorization header
403	Forbidden	Valid token but missing required scopes (RFC 6750 Section 3.1). Includes WWW-Authenticate: Bearer error="insufficient_scope", scope="<required>".	Insufficient scopes: Missing scopes: [read]
403	Forbidden	Valid token but missing required roles for the matched route	Insufficient roles: Missing roles: [admin]
404	Not Found	No route configured for the requested path	No route configured for path: /api/unknown
405	Method Not Allowed	Route exists but the HTTP method is not in the allowed set. Includes Allow header listing permitted methods.	Method POST not allowed on /health. Allowed: [GET]
409	Conflict	Returned by the /attachments endpoint when: (a) the parent route does not accept attachments (attachmentsMaxCount is 0), (b) the attachment window is closed (parent has transitioned past COLLECTING_ATTACHMENTS or PROCESSED), or (c) the route’s attachments-max-count is exceeded.	Attachment limit reached: 5
413	Payload Too Large	Request body exceeds the configured rest.gateway.max.request.size limit (default 1 MB) or per-route restapi.<name>.max-request-size	Request body size 2097152 exceeds maximum 1048576 bytes
422	Unprocessable Content	Request body fails JSON Schema validation (when a route specifies schema). Includes a violations array with JSON Pointer paths and messages.	Request body failed JSON Schema validation
500	Internal Server Error	Unexpected internal error during request processing. Full stack trace logged via CuiLogger.	An unexpected error occurred
503	Service Unavailable	Request queue is full (back-pressure). The NiFi flow cannot keep up with incoming requests.	Server is at capacity, please retry later

3. WWW-Authenticate Header (RFC 6750)

Authentication failures include the WWW-Authenticate header per RFC 6750:

Scenario	Header Value
Missing token	WWW-Authenticate: Bearer
Invalid token	WWW-Authenticate: Bearer error="invalid_token"
Insufficient scope	WWW-Authenticate: Bearer error="insufficient_scope", scope="<required>"

4. 422 Validation Error Details

When a route has JSON Schema validation enabled, the 422 response includes a violations array:

{
  "type": "...",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Request body failed JSON Schema validation",
  "violations": [
    {
      "pointer": "/name",
      "message": "required property 'name' not found"
    },
    {
      "pointer": "/age",
      "message": "Value is [string] but should be [integer]"
    }
  ]
}

Each violation contains a RFC 6901 JSON Pointer and a human-readable message.

5. JWT Configuration Log Messages

JWT infrastructure messages are logged through de.cuioss.nifi.jwt.JwtLogMessages in the format JWT-<identifier>: <message>. The entries below are the ones this documentation set refers to explicitly; JwtLogMessages is the authoritative and complete list.

Identifier	Level	Message Template	When Logged
JWT-115	WARN	Issuer %s configures name '%s' but no 'issuer'. 'name' is no longer read as the issuer identifier; set 'issuer' to the identity provider's 'iss' claim value	An issuer declares issuer.<name>.name but no issuer.<name>.issuer. Issuer identity is derived solely from issuer.<name>.issuer, so the issuer is skipped. The first %s is the issuer group id (the <name> segment of the property key), the second the configured label. See Configuration Reference for the migration note.