Understanding Problem Details responses

STARS APIs use RFC 9457 Problem Details responses to report request-processing errors, including validation failures that prevent a request from being accepted.

Problem Details responses may be returned for:

• schema validation failures

• domain validation failures

Validation findings produced by the STARS validation framework are returned separately as validation results and are documented separately.

See also Errors and validation responses.

Problem Details and validation results

VDS uses two different mechanisms to communicate validation issues.

Use the response type received to determine whether the issue occurred during request validation or during validation processing.

Schema validation

Schema validation failures occur when a request does not satisfy requirements that are described by, or can reasonably be inferred from, the OpenAPI specification.

Examples include:

• missing required properties

• invalid data types

• invalid formats

• invalid enumeration values

• values that exceed supported length constraints

Where multiple schema validation failures are detected, they are returned using the errors collection.

Example

Interpretation

• Multiple validation failures were detected

• Each affected request field is identified in the errors collection

• The request cannot be accepted until the validation failures are corrected

• The grouped schema validation rule is identified using technicalRuleId BRTS90320.

Domain validation

Domain validation failures occur when a request violates validation requirements that cannot be fully described by, or inferred from, the OpenAPI specification.

These validation requirements are documented in the STARS rules catalogue.

Where a domain validation failure occurs, the response may identify the associated validation rule using a technicalRuleId.

Example

Interpretation

• A specific validation rule failed

• The failed validation rule is identified by technicalRuleId

• The detail attribute provides additional information about the validation failure

• The request cannot be accepted until the validation failure is corrected

Other Problem Details responses

Problem Details is also used for non-validation scenarios.

For example, a resource not found response returns:

• type = https://api/errors/not-found 

• status = 404

• technicalRuleId = BRTS90190

These responses follow the same general ProblemDetails pattern but are not validation failures.

Problem Details response attributes

The following attributes are commonly used when interpreting a Problem Details response

Understanding Problem Details attributes

Type

The type attribute identifies the category of problem.

Applications may use this value to support programmatic handling of Problem Details responses.

Title

The title attribute provides a short summary of the problem.

The value should be interpreted together with the detail attribute or the errors collection.

Status

The status attribute identifies the HTTP status code associated with the response.

A non-success status code indicates that the request could not be accepted.

Detail

The detail attribute provides additional information about a specific validation failure.

Where present, the value assists in understanding why the request was rejected and what needs to be corrected.

Example:

Errors

The errors attribute contains field-level validation failures.

Example:

The property name identifies the affected request field and the associated message describes the validation failure.

Multiple entries may be returned where multiple validation failures are detected within the same request.

Technical Rule Identifier

The technicalRuleId identifies the validation rule associated with the Problem Details response.

The value supports:

• troubleshooting

• support investigations

• correlation with validation results and other STARS documentation

• mapping to STARS rules catalogue documentation

Instance

The instance attribute identifies the API path associated with the request that produced the Problem Details response.

The value identifies the request endpoint rather than the specific field or resource that failed validation.

Trace Id

The traceId supports troubleshooting and support investigations.

When seeking assistance, provide the associated traceId.

Relationship to the STARS rules catalogue

Some Problem Details responses include a technicalRuleId.

The technicalRuleId supports:

• troubleshooting

• support investigations

• correlation with validation results

• mapping to STARS rules catalogue documentation

• understanding the validation requirement that failed

Use the associated rule documentation when investigating recurring validation failures.

Processing Problem Details responses

When a Problem Details response is returned:

1. Review the HTTP status code

2. Review the technicalRuleId

3. Review the detail message or errors collection

4. Identify the affected fields or validation requirements

5. Correct the request data

6. Resubmit the request

Summary

Problem Details responses are returned when validation prevents a request from being accepted.

• technicalRuleId identifies the associated validation rule

• errors identifies affected request fields where multiple validation issues are detected

• detail provides additional information about a validation failure

• instance identifies the API path associated with the request

• traceId supports troubleshooting and support investigations

• Validation findings produced by the STARS validation framework are returned separately as validation results