# Requests

A **request** allows to follow the progress of a user request and identify a possible failure. 

Most requests to the system return a `requestId` in the response body, which may be used to inquire on the status of the request.

It is also possible and encouraged to provide a user-defined requestId using the `requestId` HTTP header when submitting intents or when approving/refusing them, this has several advantages:
- If the connection is interrupted between the request and the response the `requestId` will still be known by the caller, which can then check if the request has been submitted to Harmonize or not
- If the caller retries to submit another request with an already-used `requestId`, Harmonize will prevent this by returning an error, in order to avoid the involuntary replay of a request

**Users** satisfying any of the below conditions are allowed to read a **request** status:
- user is the originator of the request (even if it does not have a read access to `requests`)
- user is in the originator domain and has a role granting him read access to `requests`
- user is in the target domain and has a role granting him read access to `requests`

A **request** will return, in particular, the following fields:
- `lastModifiedAt`, which tracks the last update timestamp of the request;
- `status`, which may be `Processing`, `Succeeded` or `Failed`; a `Failed` status also exposes an additional field detailing the failure reason.
- `history`, which tracks all the intermediate steps of the user request, with details regarding the source component, the status, an eventual hint in case of failure, and a timestamp;

## Get request state

 - [GET /v1/domains/{domainId}/requests/{requestId}](https://docs.ripple.com/products/custody/devbox/requests/getrequeststate.md)

## Get all user requests state

 - [GET /v1/me/requests](https://docs.ripple.com/products/custody/devbox/requests/getalluserrequestsstate.md)

## Get all user requests state in domain

 - [GET /v1/domains/{domainId}/requests](https://docs.ripple.com/products/custody/devbox/requests/getalluserrequestsstateindomain.md)