# Troubleshooting

> What happens when the service is down, connection errors, PHP intl, the visitor IP behind a proxy, check limits and test mode.

## When the TrustOrder service is down

TrustOrder fails open. If the service is slow or unavailable, nothing is hidden and every order goes through. The checkout waits at most 1.5 seconds for the answer.

Any error (timeout, network, unexpected answer, no API key) means nothing is hidden and the order goes through. The order gets the **Not checked** badge, so you can look at it yourself.

## Connection test errors and the last error

The **Overview** page shows the connection test on the **Connection** card and the most recent problem under **Last error**, in plain words, with the time it was logged. If there was none, it says "No error so far."

| Message | What to do |
|---|---|
| The API key was not accepted. Check that you copied the whole key. | Paste the full key again. |
| The account or shop behind this key is suspended or disabled. Contact upTools. | Contact upTools. |
| Too many requests in a short time. TrustOrder retries by itself. | Nothing; it retries. |
| The daily check quota is used up. Until tomorrow every payment method stays available. | Wait until tomorrow. |
| The service did not answer in time. The order went through with every payment method. | Nothing; the order went through. |
| The service could not be reached from this server (network or DNS error). | Ask your host to check the server's network and DNS. |
| Temporary error on the service side. | Nothing; try again later. |
| The service refused a request as invalid. Update the plugin if this repeats. | Update the plugin. |
| No API key is saved. | Add a key: [Install and connect](https://docs.uptools.io/trustorder/wordpress/install/). |
| A risky buyer would have had no payment method left, so nothing was hidden. Set a fallback payment method. | Pick a fallback method: [Settings](https://docs.uptools.io/trustorder/wordpress/settings/#payment-methods-to-hide-and-fallback-methods). |
| A local check limit was reached (per session or per visitor network); those buyers were not checked. | See [check limits](#check-limits). |

If the account shows **Awaiting approval**, checks already work; upTools approves the account soon.

## Accented characters (PHP intl)

The **Status** list on the **Overview** page shows whether **Accented characters (PHP intl)** is **Available** or **Missing**.

When the PHP `intl` or `mbstring` extension is missing, values with non-ASCII characters (accented addresses, international e-mail domains) are not hashed, and an order whose e-mail contains such characters is not checked. The admin shows a notice. Ask your host to enable `intl` and `mbstring`.

## Visitor IP behind a proxy

TrustOrder limits checks per visitor network, so it needs the real visitor address.

- The visitor network comes from `REMOTE_ADDR`.
- `X-Forwarded-For` is never trusted.
- If your shop is behind a proxy or load balancer, return the real visitor address from the `trustorder_client_ip` filter.
- When the visitor address is private, carrier-grade NAT (100.64.0.0/10), loopback, link-local or IPv6 ULA, which usually means a proxy sits in front of the shop, the network limits are skipped until you set `trustorder_client_ip`. The per-session limits still apply.
- IPv4-mapped IPv6 addresses (`::ffff:a.b.c.d`) count as IPv4, and IPv6 addresses are grouped per /64.

## Check limits

To protect your API quota, TrustOrder limits the number of checks:

- While the buyer types, at most 5 checks run per checkout session.
- Placing an order has its own limit: at most 3 checks per session.
- Per visitor network: at most 20 browsing checks and 10 place-order checks per 30 minutes.
- Shop-wide: at most 300 browsing checks per hour.

The filters `trustorder_ip_check_limit`, `trustorder_submit_ip_check_limit` and `trustorder_hourly_check_limit` change these limits.

What happens when a limit is reached:

- When the place-order limit is reached for a buyer who has not been checked yet, the risky payment methods stay hidden. The last remaining payment method is never hidden.
- A place-order check that fails because the service is unreachable or returns a server error does not use up the limit, at most 3 times per session and 6 times per visitor network in 30 minutes (filter: `trustorder_network_refund_limit`).
- The **Overview** page shows **Hourly check limit** and **Place-order limit per network** as **Reached** if they were reached in the last hour, and the admin shows a dismissible warning.

Without a persistent object cache, the counters are approximate when many requests arrive at the same moment. With one, every count is atomic and a denied check uses up nothing. If the object cache errors, the counters fall back to transients for that request, so the limits still apply.

## Order reports that do not go out

Reports are sent in the background. When the service is busy or unreachable, the plugin retries after 1, 5, 30 and 120 minutes, then marks the report as failed. To check or resend one order, use `wp trustorder signal status` and `wp trustorder signal send` ([WP-CLI](https://docs.uptools.io/trustorder/wordpress/wp-cli/#order-reports)).

Deactivating the plugin cancels its pending background jobs. After reactivating, start the [backfill](https://docs.uptools.io/trustorder/wordpress/orders/#backfill-past-orders).

## Test mode

A `to_test_...` key puts the shop in test mode: the **Overview** and **Settings** pages show a **Test mode** badge, and the data goes into a separate test database. Use a `to_live_...` key for the live shop.

- Test and live keys keep separate reports. After a key switch, an order is sent again to the new environment.
- Switching keys does not withdraw reports already sent with the other key.
- The backfill keeps its progress per environment and runs only for the environment of the saved key.

## API

The TrustOrder API is documented here: [TrustOrder API](https://docs.uptools.io/trustorder/api/).
