# Requests and responses

This section outlines the standard behaviors for API requests and responses across the Solaris platform.

## Parameter guidelines

Follow these rules when constructing API requests to avoid validation errors:

* **Whitespace:** Parameter values must **not** begin or end with whitespace. This triggers an exception error.
* **Null Values:** The API ignores `null` values in the request body. This is particularly relevant for `PATCH` requests (sending `null` does not delete a value; it does nothing).
* **Case Sensitivity:** The API is **case-sensitive**, including enumeration values. Incorrect casing triggers a validation error.
* **Unknown Parameters:** If you supply a parameter that does not exist for the resource, the API **ignores** it (sanitization) rather than throwing an error.


**Example: Ignored parameters**

In this example, `does_not_have_this_parameter` is not part of the resource schema, so the API ignores it and processes the valid parameters.


```json POST /v1/example_resource
{
  "valid_parameter_1": "Value1",
  "valid_parameter_2": "Value2",
  "does_not_have_this_parameter": "Value3"
}
```

**Response:**


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

## Pagination

Use pagination for endpoints that return large lists (e.g., bookings, transactions). This improves response times by processing data in batches.

### Request parameters

Append these query parameters to your request URL:

| Parameter | Default | Maximum | Description |
|  --- | --- | --- | --- |
| `page[number]` | `1` | N/A | The specific page of results to return. |
| `page[size]` | `10` | `1000` | The number of items per page. |


**Example request:**


```shell
GET /v1/transactions?page[number]=2&page[size]=15
```

### Response headers

Paginated responses include specific headers defined by [RFC 5988](https://tools.ietf.org/html/rfc5988):

* `total`: The total count of available entries.
* `per-page`: The number of entries returned in this response.
* `link`: Navigation links for `first`, `last`, `prev`, and `next` pages.


**Example response:**


```http
HTTP/1.1 200 OK
total: 64
per-page: 15
link: https://api.solarisbank.de/v1/transactions?page[number]=1&page[size]=15>; rel="first", ...
Content-Type: application/json

[ ... 15 items ... ]
```

## Sorting

You can sort the response of supported `GET` requests using the `sort` query parameter.

* **Ascending (Default):** `sort={property_name}`
* **Descending:** `sort=-{property_name}` (Prefix with a minus sign)


**Example: Sort bookings by date (Ascending)**


```shell
GET /v1/accounts/bookings?sort=recorded_at
```

**Example: Sort bookings by date (Descending)**


```shell
GET /v1/accounts/bookings?sort=-recorded_at
```

## Rate limiting

To ensure platform stability, Solaris enforces the following limits:

* **Concurrency:** Maximum of **255** concurrent API calls per partner.
* **SMS:** Maximum of **60 SMS messages** per recipient phone number per hour.


## Timeouts

Idle requests to the Solaris API time out after **150 seconds**.

Only retry a request after the timeout period has expired or after you receive a definitive error response from the API.