> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ethioreview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Common HTTP status codes and how to fix EthioReview API and widget failures.

EthioReview returns standard HTTP status codes. Error bodies usually include a short `message` you can log or surface in your own UI.

## Status codes

| Status | Meaning | Typical cause |
| - | - | - |
| `400` | Bad request | Missing fields, invalid widget config, or mismatched environment |
| `401` | Unauthorized | Missing or invalid `Authorization` / `X-Widget-Key` |
| `403` | Forbidden | Origin not allowlisted, wrong org, or sandbox/production mismatch |
| `404` | Not found | Unknown organization, widget, or shop ID |
| `429` | Too many requests | Rate limit exceeded — retry with backoff |
| `5xx` | Server error | Transient platform issue — retry later |

## Auth failures

### Missing or wrong key

```http theme={null}
GET /api/v1/widgets/businesses/{orgId}/reviews
X-Widget-Key: pk_test_WRONG
```

Returns `401` or `403` if the publishable key is missing, revoked, or not recognized.

### Secret key in the browser

Partner routes expect:

```http theme={null}
Authorization: Bearer sk_test_YOUR_SECRET
```

If you send a publishable key (`pk_*`) as a Bearer token, the request fails. Keep secrets on your server only.

## Origin / CORS failures

Browser widget calls check `Origin` (or `Referer`) against the API client's **allowed origins**.

Symptoms:

* Network tab shows `403`
* Console shows a CORS error
* Dashboard **Sandbox test** preview is blank

Fix: add the exact origin (scheme + host + port, no path) under **Integrations → API keys**. See [Allowed origins](/api-keys/allowed-origins.md).

## Environment mismatch

A sandbox key (`pk_test_*`) cannot resolve a production widget, and a live key (`pk_live_*`) cannot resolve a sandbox widget. The API responds with `403` and a message like **Widget environment mismatch**.

> [!WARNING]
>
> Always pair `pk_test_*` with a **Sandbox** widget and `pk_live_*` with a **Production** widget.

## Empty reviews (not always an error)

A `200` with an empty `reviews` array means the request succeeded but no testimonials matched your filters (for example `minStars: 4` on an org with no active 4+ star reviews).

In **sandbox**, you should always see synthetic testimonials when the key and widget are configured correctly. If sandbox returns empty, check the key environment and allowed origins first.

## Debugging checklist

**1. Confirm the key prefix**

`pk_test_*` for sandbox, `pk_live_*` for production.

**2. Confirm the widget environment**

**Integrations → Review widgets** — environment must match the key.

**3. Confirm allowed origins**

Exact match for localhost or your live domain.

**4. Hit the API directly**

```bash theme={null}
curl -H "X-Widget-Key: pk_test_YOUR_KEY" \
  "https://api.ethioreview.com/api/v1/widgets/businesses/YOUR_ORG_ID/reviews?limit=5"
```

[Authentication →](/authentication.md) · [Allowed origins →](/api-keys/allowed-origins.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.