# Authentication, errors and limits

> The rules every Releva API call shares. The base URL, which key to send (Access Token or Secret Key), the request format and 800 KB body limit, status codes and error messages, rate limits and versioning.

Every Releva API call follows the same rules for keys, request format, errors and limits. This page describes them once. The page for each call covers only what is specific to that call.

## Base URL

All calls go to:

```plaintext
https://releva.ai/api/v0
```

Use HTTPS. A plain HTTP request answers `400` with `{"message":"We do not support non-HTTPS requests."}`.

## Which key to send

Every shop in Releva has two keys. Both are UUIDs, so you cannot tell them apart by their format. You find both on **Settings › Shop & Integration**, on the **General** tab. See [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

| Key              | Used by                                                                                                    | Where it may appear                                                       | How to send it                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Secret Key**   | Calls from your server: catalog, orders, events, profiles, consent and companies                           | Only on your server. Never put it in a browser, an app or front-end code. | `authorization: Bearer $RELEVA_SECRET_KEY`                                                              |
| **Access Token** | Calls from the storefront and apps, such as the page push that the JavaScript SDK and the mobile SDKs send | In your page source and your app. That is by design.                      | `authorization: Bearer $RELEVA_ACCESS_TOKEN`, or in the path on the routes that end in `/{accessToken}` |

The header must read exactly `Bearer` followed by a space and the key. The scheme is case-sensitive, so `bearer` is rejected.

The Partner API uses a third credential, the `x-rlv-partner-token` header. See [Partner API overview](https://releva.ai/documentation/reference/partners/overview/).

### Authentication errors

Authentication failures answer **`400`**, not `401`.

| Problem                      | Message (Secret Key calls)                                                    | Message (Access Token calls)                                                                                         |
| ---------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| No key sent                  | `Authorization header is missing.`                                            | `Authorization header is missing, and accessToken url parameters is also missing. At least one of them is required.` |
| Header is not `Bearer <key>` | ``Authorization header is malformed. It should look like `Bearer <string>`.`` | Same message                                                                                                         |
| The key is not a UUID        | `Authorization header contains an invalid Bearer token.`                      | `The access token you provided is invalid.`                                                                          |
| No shop has this key         | `Domain with the provided secret key cannot be found.`                        | `Domain with the provided access token cannot be found.`                                                             |

`Domain with the provided secret key cannot be found.` usually means you sent the **Access Token** where the **Secret Key** belongs, or a key from another shop.

A shop that has been switched off answers **`402`** with `Domain is disabled. Please reach out to support@releva.ai to enable it.`

## Request format

* Send JSON with `content-type: application/json`. With any other content type the body is not read, and the call fails validation with `400`.
* A body that is not valid JSON answers `400` with the parser’s message, for example `Unexpected end of JSON input`.
* Bodies are limited to **800 KB**. A larger body answers `413` with `{"message":"request entity too large"}`.
* Validation errors answer `400`. When a request breaks several rules, the messages are joined into one `message`, separated by spaces. Where a call rejects keys it does not know, the message names them, for example `The object 'profiles[0].profile' contains forbidden keys: 'tags'.`

A minimal call with the Secret Key:

```plaintext
curl -X POST 'https://releva.ai/api/v0/unsubscribe' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{ "email": "maria@example.com" }'
```

## Responses and status codes

Errors have one shape:

```plaintext
{ "message": "Authorization header is missing." }
```

There is no separate error code or field property. There are two exceptions: the `409` described below, and the `400` from `POST /roles` when a role has neither an email nor a phone number, which is the plain-text body `At least one of (email, phoneNumber) is required for each role!`, not JSON.

| Status | Meaning                                                                                                                                                                                                                                                                                                                                                                      |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | The call succeeded and the body holds the result, for example a profile from `GET /profiles`.                                                                                                                                                                                                                                                                                |
| `202`  | Accepted. Most server writes answer `202` with the body `{}`: products, orders, refunds, events, profiles, registrations, unsubscribes, companies and roles.                                                                                                                                                                                                                 |
| `400`  | Authentication failed, the body could not be read, or validation failed. The `message` says which.                                                                                                                                                                                                                                                                           |
| `402`  | The shop is switched off. Calls that serve personalized content, such as the page push and search as you type, also answer `402` when the shop’s usage is over its plan, with `Value delivery is paused for this domain because usage exceeded the plan limit. Please raise your limit or reach out to support@releva.ai to resume.` Calls that only send data keep working. |
| `404`  | A read found nothing, for example `{"message":"Profile not found."}` from `GET /profiles`.                                                                                                                                                                                                                                                                                   |
| `409`  | A subscribe call sent with `rejectAlreadySubscribed` found the customer already subscribed. The body is `{"code":"alreadySubscribed"}`.                                                                                                                                                                                                                                      |
| `413`  | The body is larger than 800 KB.                                                                                                                                                                                                                                                                                                                                              |
| `429`  | Too many requests to a rate-limited call. See [Rate limits](https://releva.ai/documentation/reference/get-started/authentication-errors-and-limits/#rate-limits).                                                                                                                                                                                                                                                                                                   |
| `500`  | An unexpected error. The body is `{"message":"An internal error occurred."}`. Try again later.                                                                                                                                                                                                                                                                               |

## Body size limits

* **800 KB** per request body on every call that takes JSON.
* Most write calls take a list, for example `products` or `profiles`. There is no maximum number of items in a list other than the 800 KB body limit. Split a large update into several requests.

## Rate limits

Some storefront calls, made with the Access Token, have rate limits. Each counts requests over a 15-minute window.

| Call                                                                   | Limit                                                                                                                                               |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /subscribe/check`                                                | 30 requests per 15 minutes per IP address. Every request counts.                                                                                    |
| `POST /subscribe/request` with `rejectAlreadySubscribed: true`         | 30 failed requests per 15 minutes per IP address. Successful requests do not count, and requests without `rejectAlreadySubscribed` are not limited. |
| `POST /orders/status-reference/{accessToken}` (`Releva.lookupOrder()`) | 10 requests per 15 minutes per shop and IP address. Every request counts.                                                                           |

Over the limit, the call answers `429` with the plain-text body `Too many requests, please try again later.`, not JSON. The `RateLimit` and `RateLimit-Policy` response headers show the limit and when the window resets.

Server calls made with the Secret Key have no rate limit.

## Versioning

* Every call is under `/api/v0`. There is no other version.
* Changes to the API are listed in the [API changelog](https://releva.ai/documentation/changelog/api/).
* Where a call rejects keys it does not know, send a new field only after it appears in the reference for that call.

## Next steps

* [Build your integration](https://releva.ai/documentation/reference/get-started/build-your-integration/): See what to build, in order, from your keys to a verified integration.
* [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/): Copy the two keys this page describes.
* [Endpoints the Releva SDKs call](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/): See the storefront and app calls that use the Access Token.
* [Subscribe a customer](https://releva.ai/documentation/reference/consent/subscribe-a-customer/): Make your first server call with the Secret Key.