Skip to main content

Error Handling

Overview​

All Connector NG implementations use a standardized error response format based on RFC 9457 — Problem Details for HTTP APIs. This ensures consistent, machine-actionable, and human-readable error information across all connectors and their upstream systems.

Media type​

Error responses use the application/problem+json content type (per RFC 9457 §6.1). The HTTP status code must be 4xx or 5xx.

text
Content-Type: application/problem+json
note

application/problem+xml is not supported.

Problem object​

Each error response body is a JSON object with the following fields:

FieldTypeRequiredDescription
typestringyesA URI reference identifying the problem type. Resolves to a documentation page on this site.
titlestringnoShort, human-readable summary of the problem type (does not change between occurrences).
statusnumberyesHTTP status code. Must match the actual response status code.
detailstringnoHuman-readable explanation specific to this occurrence of the problem.
instancestringnoA URI reference that identifies the specific occurrence (e.g., request path or operation ID).

ILM extensions​

In addition to the standard fields, ILM connectors include the following extension properties:

ExtensionTypeRequiredDescription
errorCodestringyesStable error code from the ErrorCode enum (e.g., VALIDATION_FAILED).
timestampstringyesISO 8601 / RFC 3339 timestamp of when the error occurred.
retryablebooleanyesWhether the same request can be safely retried. It follows the error code, see Problem types.
correlationIdstringnoTrace identifier from X-Request-Id or W3C Trace Context, used for cross-system correlation.
retryAfterSecondsintegernoBackoff hint in seconds before retrying. Present only when retryable is true (default: 30).

Additional properties​

Beyond the fixed extension fields above, ProblemDetailExtended exposes a generic properties map (inherited from Spring's ProblemDetail). Implementations use this map to attach any additional context relevant to the specific error. Per RFC 9457, these entries are serialized as top-level members of the JSON object alongside the standard fields.

A common example is a causes array added for validation errors, where each entry describes one failed field:

Property keyValue typeExample use
causesarray of objectsPer-field validation failures (see VALIDATION_FAILED)

Each causes entry typically contains:

FieldTypeDescription
namestringField or parameter that failed (e.g., csr, subject.commonName)
reasonstringHuman-readable explanation of why it failed
rulestringMachine-readable rule identifier (e.g., PKCS10.DECODE, RFC5280.CN.LENGTH)

Other implementations may add different properties relevant to their error type.

Example​

json
{
"type": "https://docs.otilm.com/problems/common/VALIDATION_FAILED",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields failed validation.",
"instance": "/v1/certificates/requests",
"errorCode": "VALIDATION_FAILED",
"correlationId": "f5a2e0e0c1ec41d4b7208b5b0c7bc7d9",
"timestamp": "2025-09-08T12:41:22Z",
"retryable": false,
"causes": [
{
"name": "csr",
"reason": "PEM is not a valid PKCS#10 CSR (base64 decode failed)",
"rule": "PKCS10.DECODE"
},
{
"name": "subject.commonName",
"reason": "Common Name exceeds 64 characters",
"rule": "RFC5280.CN.LENGTH"
}
]
}

The causes array appears as a top-level property in the JSON because Spring's ProblemDetail flattens the properties map into the response body.

Problem types​

Problem type URIs follow the pattern https://docs.otilm.com/problems/{category}/{ERROR_CODE}, where ERROR_CODE is the exact name of the ErrorCode enum value. Each URI resolves to a documentation page with a full description, common causes, and remediation steps.

Only REQUEST_TIMEOUT, RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE and GATEWAY_TIMEOUT are retryable.

Common types​

These problem types are shared across all ILM services and connectors:

Error codeType URIHTTP StatusRetryableDescription
VALIDATION_FAILED/common/VALIDATION_FAILED422noOne or more input fields failed validation
RESOURCE_NOT_FOUND/common/RESOURCE_NOT_FOUND404noThe requested resource does not exist
RESOURCE_ALREADY_EXISTS/common/RESOURCE_ALREADY_EXISTS409noA resource with the same identifier already exists
BAD_REQUEST/common/BAD_REQUEST400noMalformed or structurally invalid request
ATTRIBUTES_ERROR/common/ATTRIBUTES_ERROR400noError processing connector attributes
UNAUTHORIZED/common/UNAUTHORIZED401noAuthentication credentials missing or invalid
FORBIDDEN/common/FORBIDDEN403noAuthenticated but not authorized for this operation
REQUEST_TIMEOUT/common/REQUEST_TIMEOUT408yesOperation timed out waiting for upstream response
OPERATION_NOT_SUPPORTED/common/OPERATION_NOT_SUPPORTED501noOperation is not implemented by this connector
RATE_LIMIT_EXCEEDED/common/RATE_LIMIT_EXCEEDED429yesToo many requests in the allowed time window
SERVICE_UNAVAILABLE/common/SERVICE_UNAVAILABLE503yesService or a critical dependency is temporarily unavailable
GATEWAY_TIMEOUT/common/GATEWAY_TIMEOUT504yesAn upstream system did not answer in time
INTERNAL_SERVER_ERROR/common/INTERNAL_SERVER_ERROR500noUnexpected server error — report with correlation ID

Connector types​

These problem types belong to connector operations. A type specific to one interface carries the interface in its URI, https://docs.otilm.com/problems/connector/{interface}/{ERROR_CODE}:

Error codeType URIHTTP StatusRetryableDescription
UPSTREAM_ERROR/connector/UPSTREAM_ERROR502noThe connector's upstream system returned an error
CREDENTIAL_INVALID/connector/CREDENTIAL_INVALID401noThe upstream system refused the credentials the connector presented
POLICY_VIOLATION/connector/POLICY_VIOLATION422noA policy of the upstream system refused the request
OPERATION_PAST_POINT_OF_NO_RETURN/connector/OPERATION_PAST_POINT_OF_NO_RETURN422noThe operation has gone too far to be stopped or cancelled
OPERATION_NOT_TRACKED/connector/OPERATION_NOT_TRACKED404noThe connector does not track the operation the request refers to
ATTRIBUTE_DEFINITION_NOT_FOUND/connector/ATTRIBUTE_DEFINITION_NOT_FOUND404noThe connector has no attribute definition with the requested UUID
DOCUMENT_MALFORMED/connector/DOCUMENT_MALFORMED422noThe document cannot be parsed as the declared format
DOCUMENT_TOO_LARGE/connector/DOCUMENT_TOO_LARGE413noThe document exceeds the size the connector accepts
SIGNATURE_NOT_FOUND/connector/SIGNATURE_NOT_FOUND422noThe document has no signature the operation can act on
PARAMETER_UNSUPPORTED/connector/PARAMETER_UNSUPPORTED422noA requested parameter, such as an algorithm, is not supported
CONTEXT_MISMATCH/connector/CONTEXT_MISMATCH422noThe request contradicts the context it replays
CSR_MALFORMED/connector/authority/CSR_MALFORMED422noThe CSR cannot be parsed
REVOCATION_NOT_ALLOWED/connector/authority/REVOCATION_NOT_ALLOWED422noThe certification authority does not allow the revocation
REGISTRATION_NOT_FOUND/connector/authority/REGISTRATION_NOT_FOUND422noThe certification authority does not track the registration
RENEWAL_SOURCE_NOT_FOUND/connector/authority/RENEWAL_SOURCE_NOT_FOUND404noThe certification authority cannot find the certificate to renew
CSR_SUBJECT_MISMATCH/connector/authority/CSR_SUBJECT_MISMATCH422noThe CSR subject does not match the registration
CERTIFICATE_MISMATCH/connector/authority/CERTIFICATE_MISMATCH422noThe certificate belongs to a different authority than requested
CHECKPOINT_LOST/connector/discovery/CHECKPOINT_LOST410noA stopped discovery run cannot be resumed from its checkpoint
KEY_TYPE_NOT_IMPORTABLE/connector/cryptography/KEY_TYPE_NOT_IMPORTABLE422noThe token cannot hold a key of that type or algorithm
KEY_TYPE_NOT_EXPORTABLE/connector/cryptography/KEY_TYPE_NOT_EXPORTABLE422noThe token does not release a key of that type or algorithm
KEY_MATERIAL_MISMATCH/connector/cryptography/KEY_MATERIAL_MISMATCH422noThe key is not the declared key type or algorithm
KEY_DECRYPTION_FAILED/connector/cryptography/KEY_DECRYPTION_FAILED422noThe key material does not decrypt with the supplied passphrase
EXPORTABLE_NOT_SUPPORTED/connector/cryptography/EXPORTABLE_NOT_SUPPORTED422noThe token cannot hold a key that stays exportable
KEY_NOT_EXPORTABLE/connector/cryptography/KEY_NOT_EXPORTABLE422noThe key was not created or imported as exportable