Errors

Check the HTTP status code first. The error body depends on which host you called, and some errors are plain text even when the Content-Type header says JSON, so parse defensively.

Status codes

Each endpoint's reference page lists the other errors it returns, with example bodies.

Authentication errors (401)

Every endpoint on developers.yotpo.com that needs a token returns one of these:

invalid_request means the API didn't find a token at all: send it in the X-Yotpo-Token header. invalid_token means it found one but can't use it. Tokens don't expire on their own, so this usually means the merchant uninstalled your app. See How to handle each error.

Forbidden (403)

The app-level webhook endpoints (/core/v3/applications/{application_id}/...) take your app's client ID as application_id: the 32-character Application ID you got when you registered your app. With the numeric app ID they return:

{ "message": "Forbidden" }

Rate limits (429)

Over the rate limit for an endpoint, you get 429 with a Retry-After header that says how many seconds to wait:

{
  "message": "API rate limit exceeded",
  "request_id": "41c1544aa131c145725e5862fea4c031"
}

The limits and the RateLimit-* headers on every response are in Guidelines and Conventions.

Paths the API doesn't serve (404)

A path or method that developers.yotpo.com doesn't serve returns:

{
  "message": "no Route matched with those values",
  "request_id": "5b943f4c94d45a495bc5fe7094092e60"
}

This includes a real path called with the wrong method, for example DELETE on a path that only supports GET: you get 404, not 405. Check the method and path against the reference page. Log request_id and include it when you contact Yotpo.

Token endpoint errors (POST /v2/oauth2/token)

These bodies aren't valid JSON, even though Content-Type is application/json. Read the status code, then search the body for the error name (invalid_client) or the missing field. Send client_id and client_secret in the request body: an Authorization: Basic header isn't read.

Storefront errors

Storefront endpoints (api-cdn.yotpo.com and storefront.yotpo.com/loyalty) need no token, so they don't return 401.

Storefront endpoints don't return 404 for a product ID Yotpo doesn't know. They return 200 with no reviews:

{
  "pagination": { "page": 0, "perPage": 5, "total": 0 },
  "bottomline": { "totalReview": 0, "averageScore": 0.0 },
  "products": [],
  "reviews": []
}

To tell "no reviews yet" apart from "wrong product ID", check that you're sending the product ID the merchant's eCommerce platform sends to Yotpo.

How to handle each error

400 Bad Request

Fix the request before you retry: sending it again unchanged returns the same error. Check the endpoint's reference page for required parameters and body fields.

401 Unauthorized

• invalid_request: send the token in the X-Yotpo-Token header. Authorization: Bearer isn't read.
• invalid_token: check that you're using the token for this store, since each store the merchant installed your app on has its own token. If the token was working before, the merchant has probably uninstalled your app. After 3 401 responses in a row for a store that used to work, mark the integration as disconnected in your product and let the merchant reinstall it (see Authenticating with OAuth 2.0).

Don't retry a 401 in a loop: it won't succeed until the token changes.

403 Forbidden

Check that application_id in the path is your app's client ID, not the numeric app ID.

404 Not Found

• no Route matched with those values: check the HTTP method and the path, including the base URL. Endpoints on other hosts (api-cdn.yotpo.com, storefront.yotpo.com/loyalty, api.yotpo.com) say so on their reference pages.
• Any other 404: the resource ID or store ID doesn't exist. Don't retry.

429 Too Many Requests

Wait the number of seconds in Retry-After, then retry. If you hit 429 often, spread your requests out and watch RateLimit-Remaining.