Errors

Every failure answers the same shape:

{
  "error": "No order ORD-10233 was recorded for your business.",
  "code": "ORDER_NOT_FOUND",
  "requestId": "5f1e0e37-2795-4a07-9564-1e19ad52a023"
}

Branch on code, never on the message. The messages are written to be read and will be improved; the codes are a contract.

Statuses

A 404 never distinguishes "does not exist" from "belongs to someone else". That is deliberate: the difference would let a key holder probe for other businesses' customers and orders.

Every code

These are the codes of the /v1 API. The sign-up form has codes of its own, listed below.

The ones worth handling by name

IDEMPOTENCY_MISMATCH (409) — you reused a key with a different body. See Idempotency.

DUPLICATE_ORDER (409) — you have already recorded a purchase under that order id. If this is a retry, use the same idempotency key and it will replay instead.

ACTIVE_REWARD_EXISTS (409) — the customer has a usable reward waiting, so this order cannot earn on top. details.reward is that reward: if the order reaches its minimumOrderCents, offer it and redeem instead; if not, record nothing for this order. See Rewards.

MINIMUM_ORDER_NOT_MET (409) — the order does not reach the reward's minimum. The message carries the figure formatted in the business's currency, and details carries minimumOrderCents, so you can show either.

CUSTOMER_NOT_FOUND (404) — that id is not one of your customers. Ids come only from POST /v1/customers/link, and they are not phone numbers.

API_KEY_DISABLED (403) — Trovy switched this key off. Rotating will not help; email developers@trovy.ca.

In the SDK

Two classes, split by whether the write might have landed:

import { isTrovyError, isTrovyConnectionError } from "@trovy/sdk";
 
try {
  await trovy.rewards.redeem(body, { idempotencyKey: order.id });
} catch (err) {
  if (isTrovyError(err)) {
    if (err.status >= 500) {
      // Our fault, and the SDK already retried. The write may have landed:
      // try again later with the same key.
      return queue.retry({ orderId: order.id });
    }
    // The API answered and decided. Final for this request.
    if (err.code === "MINIMUM_ORDER_NOT_MET") return showThreshold(err.message);
    if (err.status === 429) return backOff(err.retryAfterSeconds);
    log.error({ code: err.code, requestId: err.requestId });
    throw err;
  }
  if (isTrovyConnectionError(err)) {
    // No answer came back. The write may or may not have applied — retry with
    // the same key.
    return queue.retry({ orderId: order.id });
  }
  throw err;
}

Use the guards rather than instanceof: two copies of the package in one dependency tree give two distinct classes, and instanceof then fails on an error that is obviously ours.

The sign-up form's codes

The form reports through its onError callback: Trovy.mount, <TrovySignup> and mount from @trovy/sdk/widget alike. The customer never reads these codes: the form shows them a message written for them, or, for anything about your key or your setup, "Sign-up isn't available right now".

Calling the widget endpoints yourself you may also meet WIDGET_NOT_CONFIGURED (the key lists no origins) and ORIGIN_NOT_ALLOWED (the caller is not the form's own frame). Through the form neither arrives: the frame cannot be drawn at all, so both show up as WIDGET_UNAVAILABLE.