Skip to content

Area: Developers

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.

All calls go to:

https://releva.ai/api/v0

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

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 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.

  • 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:

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" }'

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.
  • 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.

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.

  • 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.