Skip to content

Add more failure attributes and specific errors #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bergundy merged 3 commits into from
Oct 10, 2025
Merged

Add more failure attributes and specific errors #21

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f9177b8
Add more failure attributes and specific errors
bergundy Aug 5, 2025
a2addbd
Add REQUEST_TIMEOUT handler error
bergundy Oct 10, 2025
40c81cf
H4 to H3
bergundy Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 77 additions & 30 deletions SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,10 @@ properties:
type: string
description: A simple text message.

stackTrace:
type: string
description: An optional stack trace that may be emitted in languages that support it.

metadata:
type: object
additionalProperties:
Expand All @@ -55,6 +59,10 @@ properties:
properties:
description: |
Additional JSON-serializable structured data.

cause:
# An optional nested failure structure.
$ref: '#'
```

### OperationInfo
Expand Down Expand Up @@ -141,17 +149,9 @@ The body may contain arbitrary data. Headers should specify content type and enc
**Headers**:

- `Content-Type: application/json`
- `Nexus-Operation-State: failed | canceled`

**Body**: A JSON-serialized [`Failure`](#failure) object.
- `Nexus-Operation-State: failed | canceled` (DEPRECATED)

- `409 Conflict`: Operation was already started with a different request ID.

**Headers**:

- `Content-Type: application/json`

**Body**: A JSON-serialized [`Failure`](#failure) object.
**Body**: A JSON-serialized [`Failure`](#failure) object representing an [`OperationError`](#operation-error).

### Cancel Operation

Expand All @@ -178,33 +178,80 @@ The operation token received as a response to the Start Operation method must be

**Body**: Empty.

- `404 Not Found`: Operation token not recognized or references deleted.
## Predefined Failure Types

**Headers**:
### `OperationError`

- `Content-Type: application/json`
An Operation Error represents a failed or canceled operation outcome. It may be returned responses to `StartOperation`
requests, and in the body of async completion requests.

Operation Error [`Failure`](#failure) representation is as follows:

**Body**: A JSON serialized [`Failure`](#failure) object.
```json
{
"metadata": {
"type": "nexus.OperationError",
},
"message": "<Optional error message>",
"stackTrace": "<Optional stack trace>",
Copy link

@Quinn-With-Two-Ns Quinn-With-Two-Ns Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How are we supporting stack trace and message encryption?

Copy link
Contributor Author

@bergundy bergundy Aug 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the comment below: "Arbitrary details may be added here as needed."

"cause": { /* <Optional cause> */ },
"details": {
"state": "canceled | failed",
// Aribtrary details may be added here as needed.
},
}
```

### `HandlerError`

A HandlerError represents errors while handling a request. They include an error type as defined
[below](#predefined-handler-errors). Each error type has predefined, overridable, retry semantics. Handler Errors can be
returned responses to any of the methods defined above as well as completion callbacks.

Handler Error [`Failure`](#failure) representation is as follows:

```json
{
"metadata": {
"type": "nexus.HandlerError",
},
"message": "<Optional error message>",
"stackTrace": "<Optional stack trace>",
"cause": { /* <Optional cause> */ },
"details": {
"type": "<predefined error type (e.g. INTERNAL)",
// "retryableOverride": Optional boolean.
// Aribtrary details may be added here as needed.
},
}
```

## Predefined Handler Errors
### Predefined Handler Errors

For compatiblity of this HTTP spec with future transports, when a handler fails a request, it **should** use one of the
following predefined error codes.

| Name | Status Code | Description |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BAD_REQUEST` | 400 | The handler cannot or will not process the request due to an apparent client error. Clients should not retry this request unless advised otherwise. |
| `UNAUTHENTICATED` | 401 | The client did not supply valid authentication credentials for this request. Clients should not retry this request unless advised otherwise. |
| | | |
| `UNAUTHORIZED` | 403 | The caller does not have permission to execute the specified operation. Clients should not retry this request unless advised otherwise. |
| | | |
| `NOT_FOUND` | 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible but not advised. |
| | | |
| `RESOURCE_EXHAUSTED` | 429 | Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. Subsequent requests by the client are permissible. |
| `INTERNAL` | 500 | An internal error occured. Subsequent requests by the client are permissible. |
| `NOT_IMPLEMENTED` | 501 | The handler either does not recognize the request method, or it lacks the ability to fulfill the request. Clients should not retry this request unless advised otherwise. |
| `UNAVAILABLE` | 503 | The service is currently unavailable. Subsequent requests by the client are permissible. |
| `UPSTREAM_TIMEOUT` | 520 | Used by gateways to report that a request to an upstream handler has timed out. Subsequent requests by the client are permissible. |
| Name | Status Code | Description |
| -------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BAD_REQUEST` | 400 | The handler cannot or will not process the request due to an apparent client error. Clients should not retry this request unless advised otherwise. |
| `UNAUTHENTICATED` | 401 | The client did not supply valid authentication credentials for this request. Clients should not retry this request unless advised otherwise. |
| `UNAUTHORIZED` | 403 | The caller does not have permission to execute the specified operation. Clients should not retry this request unless advised otherwise. |
| `NOT_FOUND` | 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible but not advised. |
| `REQUEST_TIMEOUT` | 408 | Returned by the server to when it has given up handling a request. The may occur by enforcing a client provided `Request-Timeout` or for any arbitrary reason such as enforcing some configurable limit. Subsequent requests by the client are permissible. |
| `CONFLICT` | 409 | The request could not be made due to a conflict. The may happen when trying to create an operation that has already been started. Clients should not retry this request unless advised otherwise. |
| `RESOURCE_EXHAUSTED` | 429 | Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. Subsequent requests by the client are permissible. |
| `INTERNAL` | 500 | An internal error occured. Subsequent requests by the client are permissible. |
| `NOT_IMPLEMENTED` | 501 | The handler either does not recognize the request method, or it lacks the ability to fulfill the request. Clients should not retry this request unless advised otherwise. |
| `UNAVAILABLE` | 503 | The service is currently unavailable. Subsequent requests by the client are permissible. |
| `UPSTREAM_TIMEOUT` | 520 | Used by gateways to report that a request to an upstream handler has timed out. Subsequent requests by the client are permissible. |

Client implementations should try to rehydrate a `HandlerError` from the serialized `Failure` object in the response
body whenever a request fails with one of the status codes listed below. If the handler error type in the `Failure`
object details doesn't match the response status code, the `Failure` object takes precendence.

If the serialized `Failure` does not represent a `HandlerError`, clients should construct a wrapper `HandlerError`,
setting the response `Failure` as the `cause` (if available) translating the response status code to the `HandlerError`
type and status text to the message.

## General Purpose Headers

Expand All @@ -220,7 +267,7 @@ Links must contain a `type` parameter that expresses how they should be parsed.

**Example**: `Nexus-Link: <myscheme://somepath?k=v>; type="com.example.MyResource"`

### `Nexus-Request-Retryable`
### `Nexus-Request-Retryable` (DEPRECATED)

Handlers may specify the `Nexus-Request-Retryable` header with a value of `true` or `false` to explicitly instruct a
caller whether or not to retry a request. Unless specified, retry behavior is determined by the
Expand Down