Authentication, errors and limits
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
Section titled “Base URL”All calls go to:
https://releva.ai/api/v0Use HTTPS. A plain HTTP request answers 400 with {"message":"We do not support non-HTTPS requests."}.
Which key to send
Section titled “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.
| 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.
Authentication errors
Section titled “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
Section titled “Request format”- Send JSON with
content-type: application/json. With any other content type the body is not read, and the call fails validation with400. - A body that is not valid JSON answers
400with the parser’s message, for exampleUnexpected end of JSON input. - Bodies are limited to 800 KB. A larger body answers
413with{"message":"request entity too large"}. - Validation errors answer
400. When a request breaks several rules, the messages are joined into onemessage, separated by spaces. Where a call rejects keys it does not know, the message names them, for exampleThe object 'profiles[0].profile' contains forbidden keys: 'tags'.
A minimal call with the Secret Key:
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
Section titled “Responses and status codes”Errors have one shape:
{ "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. |
500 |
An unexpected error. The body is {"message":"An internal error occurred."}. Try again later. |
Body size limits
Section titled “Body size limits”- 800 KB per request body on every call that takes JSON.
- Most write calls take a list, for example
productsorprofiles. 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
Section titled “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
Section titled “Versioning”- Every call is under
/api/v0. There is no other version. - Changes to the API are listed in the API changelog.
- Where a call rejects keys it does not know, send a new field only after it appears in the reference for that call.