Errors

Check the HTTP status code first. The error body depends on which host you called, and a few 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.

api.yotpo.com (V3 and V1)

Standard V3 error

Most 400, 404, 405, 409 and 422 responses:

{
  "errors": [
    {
      "message": "product already exists"
    }
  ]
}

The message says what's wrong in plain English. Log it, but don't parse it: the wording isn't a stable contract.

Other V3 error shapes

Access token errors

V1 error shape

V1 endpoints (/apps/... and /v1/apps/...) return:

{
  "status": {
    "message": "You are not authorized to access this page.",
    "code": 401,
    "error_type": "Exceptions::AccessDenied",
    "uuid": "6bb905f3-96f2-48ac-a87c-c7264aab4e38"
  }
}

Log the uuid: Yotpo support can use it to find the request. V1 validation errors on order calls list each problem, with the uuid at the top level: {"code": 400, "uuid": "17552b78-3a8d-4932-bf31-81597fdebb6f", "errors": [{"order_num": 1, "order_id": "order_1", "field": "email", "error": "missing mandatory field"}]}.

developers.yotpo.com (app partners)

Authentication errors (401)

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. App tokens don't expire on their own, so this usually means the merchant uninstalled your app.

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

Paths the API doesn't serve (404)

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

This includes a real path called with the wrong method: 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 endpoints

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 store's e-commerce platform sends to Yotpo.

How to handle each error

400 Bad Request

Fix the request before sending it again. The message names the field. Check the endpoint's reference page for required fields and formats; a retry without changes fails the same way.

401 Unauthorized

• Store token (api.yotpo.com): request a new access token with Generate access token and retry the call once. If it fails again, the secret or store ID is wrong: stop and check your configuration instead of looping.
• App token (developers.yotpo.com), invalid_request: send the token in the X-Yotpo-Token header. Authorization: Bearer isn't read.
• App token, invalid_token: check that you're using the token for this store, since each store that installed your app 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 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

On api.yotpo.com, the request has no X-Yotpo-Token header: add it. On developers.yotpo.com, check that application_id in the path is your app's client ID, not the numeric app ID. There's nothing to retry.

404 Not Found

Check the ID and the path. For orders, a 404 with products not found: ... means a line item refers to a product that isn't in your catalog yet: create the product first, then resend. On developers.yotpo.com, no Route matched with those values means the method or path is wrong.

409 Conflict

An object with that external_id already exists. If you're retrying a create after a timeout or a 5xx, a 409 usually means your first attempt succeeded: look the object up (for example Retrieve products with external_ids) instead of creating it again. See Idempotency.

429 Too Many Requests

On api.yotpo.com, the limit is 5 requests per second per store, shared by every integration using that store ID. On developers.yotpo.com, limits are per endpoint and store; see App partners guidelines and conventions. Every response carries these headers:

Wait for Retry-After (or RateLimit-Reset) seconds, then retry. If you keep getting 429, double the wait each time. To avoid it, pace your requests: when RateLimit-Remaining reaches 0, pause until the window resets. See Rate limiting for bulk-sync patterns.

5xx Server errors

Retry with exponential backoff (1 s, 2 s, 4 s, then give up and alert). Reads and PATCH updates are safe to retry. Before retrying a POST create, remember the first attempt may have gone through: retry it, and treat a 409 as success.

What to log

For every failed call, log:

• The time (UTC), HTTP method, host and path, with your store ID
• The status code and the full response body
• The external_id of the object you were sending
• The request_id from a 429 or 404 body, or the uuid from a V1 error, when present

Never log the API secret, an app secret or an access token. When you contact Yotpo support, include the method, path, time and status code, plus any request_id or uuid.