Error Responses

ESS follows the RFC 9110 HTTP response status codes standard:

100 - 199	Associated with Informational responses.
200 - 299	Associated with Successful responses.
300 - 399	Associated with Redirection responses.
400 – 499	Associated Client Error responses.
500 - 599	Associated with Server Error responses.

Per the RFC, error responses have status codes 400-599 (inclusive).

Error Response and Format

Error Response Fields

Changed in version 2.3.0.

Starting in version 2.3, ESS services can provide more information when returning HTTP errors (i.e., HTTP status codes 400-599). Specifically, all ESS services follow RFC 9457 (Problem Details for HTTP APIs). That is, all ESS services may include the fields specified in RFC 9457 (Problem Details for HTTP APIs) to provide more information:

{
  "status": <status code>,
  "title":  "<summary>",
  "detail": "<additional description/details of the error>",
  "instance": "<OpenTelemetry Span Id>"
}

status	RFC 9110 HTTP status codes.
title	Corresponding summary of the problem type.
detail	Additional details of the error.
instance	OpenTelemetry Span Id. [1].

For example:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Verifiable Credential does not match any configured shape",
  "instance": "a96e351460518c83"
}

For UMA and OIDC Broker services, they continue, as in earlier versions, to follow RFC 6749 (OAuth 2.0), and the new RFC 9457 fields are added to their error response.

{
   "status": <status code>,
   "title":  "<summary>",
   "detail": "<additional description/details of the error>",
   "instance": "<OpenTelemetry Span Id>",
   "error": "<error code per RFC6749>",
   "error_description": "<optional error description  per RFC6749>",
   // ...
}

For example:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid DPoP in ID token.",
  "instance": "0e4e8d02a4597c57",
  "error": "request_denied",
  "error_description":"Invalid DPoP in ID token."
}

[1]

You can correlate by the span ID if that particular span (unit of work) emits a log record. For more information on ESS’ support of OpenTelemetry, see Appendix: OpenTelemetry.

Error Response Format

Changed in version 2.3.0.

• For UMA and OIDC Broker services, RFC 6749 takes precedence over RFC 9457, and as such, the error responses return as application/json media type.

• For all other services following RFC 9457, the error responses return as as application/problem+json media type.

Error Pages

For error responses to browser requests, the error pages (text/html media type) returned by ESS display the new information.