# Requests and responses

This section contains information about the Solaris API's behavior regarding API requests and how it responds.

### Parameter acceptance

Please observe the following guidelines when making requests to the Solaris API:

- Parameter values passed to the API may not begin or end with a **whitespace.** This will cause the API to respond with an exception error.
- The API will ignore `null` values in the request body. This is particularly relevant for `PATCH` requests.
- The API is **case-sensitive.** This includes enumeration values. Supplying parameters or values with the wrong case will cause a validation error.
- If you supply a parameter to a `POST` or `PATCH` request that does not exist for the resource you wish to create or modify, then the API will ignore this parameter. See the example below: the schema of the resource to be created has the two parameters `has_this_parameter1` and `has_this_parameter2`, but it does not have `does_not_have_this_parameter`. The API returns a `201` response without `does_not_have_this_parameter`.


**Example request with nonexistent parameter:**


```json
// POST /v1/example_resource
{
  "has_this_parameter1": "Value1",
  "has_this_parameter2": "Value2",
  "does_not_have_this_parameter": "Value3"
}
```

**Example response:**


```json
// HTTP/1.1 201 Created
{
  "id": "6d768d88f291f5744f9f30e9c6f2efd4ceml",
  "has_this_parameter1": "Value1",
  "has_this_parameter2": "Value2"
}
```

### Pagination

Solaris recommends using **pagination** in API requests that would return a lot of results (e.g., retrieving customer bookings or transactions). Pagination improves the loading time for the API response by processing it in batches instead of all at once.

Endpoints that allow pagination include special pagination headers as defined in the [RFC 5988 web linking standard](https://tools.ietf.org/html/rfc5988):

- `total`: The total count of entries to be returned.
- `per_page`: The number of entries per page.


You can use the following query parameters to paginate an API request:

- `page[number]`: Specifies the number of pages of results to return. The default value is `1`.
- `page[size]`: Specifies the number of objects to return on each page of results. The default value is `10`, and the maximum value is `1000`.


Append the pagination parameter to the request URL with the desired value as follows:

**Example request using pagination:**


```shell
GET /v1/<resource>/{resource_id}/<event>?page[number]=2&page[size]=15
```

In this example, the API will return two pages of results with 15 entries each.

**Example response:**


```http
HTTP/1.1 200 OK
total: 64
per-page: 15
link: <:env/v1/<resource>/<resource_id>/<event>?page[number]=1&page[size]=15>; rel="first", ...
Content-Type: application/json
  ...
```

#### Link attribute

The example response makes use of an additional header attribute called `link`. Although the specification lists a wide range of uses for this field, Solaris only uses links for the `first`, `last`, `prev` (previous) and `next` pages of the response. `prev` and `next` are respectively omitted with the first and last page of the resource.

Each `link` in this list is followed by an optional link parameter. Solaris only uses `rel` to indicate relations between pages within the response. URIs in this list are generally URL-encoded, i.e., special characters such as brackets ([]) or spaces are escaped to their equivalent percent-literal notation.

### Sorting

As with pagination, the Solaris API offers the option to sort the response of some `GET` requests by a specific property using a query parameter:

`sort={name_of_property}`

The [API reference](/api-reference/) indicates which sorting options are available for each `GET` request.

The API will sort the response in **ascending** order by default. To sort in **descending** order, include a `-` before the property's name. See the examples below for more info:

**Example request—sort bookings by `recorded_at`, ascending:**


```shell
GET :env/v1/escrow/account/bookings?sort=recorded_at
```

**Example request—sort bookings by `recorded_at`, descending:**


```shell
GET :env/v1/escrow/account/bookings?sort=-recorded_at
```

### Rate limiting

You may make **255** concurrent API calls at a time.

Endpoints that send SMS OTPs are limited to **60 SMS messages** per recipient phone number per hour.

### Timeouts and retries

Idle requests to the Solaris API will time out after **150 seconds.** You should only retry requests after the timeout period has expired or after the API sends a response.