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

# Troubleshooting

> Diagnose and fix common Wearo integration issues.

# Troubleshooting

## Error response format

All API errors follow this format:

```json theme={"dark"}
{
  "error": "Error message description",
  "hint": "Optional hint for resolution"
}
```

## Error codes reference

| HTTP    | Error                                     | Cause                             | Solution                                                        |
| ------- | ----------------------------------------- | --------------------------------- | --------------------------------------------------------------- |
| **400** | `userPhoto and productImage are required` | Missing fields                    | Provide both `userPhoto` and `productImage` (URL or Base64)     |
| **400** | `Failed to fetch user photo from URL`     | URL not accessible                | Verify the URL is publicly reachable                            |
| **400** | `Failed to fetch product image from URL`  | URL not accessible                | Verify the URL is publicly reachable                            |
| **400** | Image too small                           | Image smaller than 1 KB           | Send a valid, full-size image                                   |
| **401** | `Authentication required`                 | Missing header or invalid key     | Send your key in the `X-API-Key` **header** (not a query param) |
| **402** | `Insufficient credits`                    | No credits                        | Purchase credits in your dashboard                              |
| **402** | `Payment past due`                        | Subscription failed               | Update your payment method                                      |
| **403** | `API key is inactive`                     | Key deactivated                   | Create a new key                                                |
| **403** | `Domain not authorized`                   | Origin not whitelisted            | Add your domain to the key's whitelist                          |
| **403** | `Origin header required`                  | Missing header                    | Add `Origin` header to your request                             |
| **422** | `ai_content_rejected`                     | Content rejected by the AI engine | Use compliant, appropriate images                               |
| **500** | `AI generation failed`                    | AI model error                    | Retry; contact support if persistent                            |
| **500** | `Failed to save result`                   | Storage error                     | Retry; contact support if persistent                            |

<Note>
  A **404 from Cloudflare** (`{"error":"requested path is invalid"}` with a `CF-RAY` header) is not a Wearo error — the request URL is wrong. The correct endpoint is `POST https://api.wearo.io/functions/v1/tryon-api`.
</Note>

## Widget button not appearing

<AccordionGroup>
  <Accordion title="Check the product selector">
    Open DevTools and test your selector in the console:

    ```javascript theme={"dark"}
    document.querySelectorAll('.product__media img')
    ```

    If it returns 0 elements, your selector doesn't match. Inspect the product
    image and copy its class or ID.

    [Custom selectors guide →](/configure/custom-selectors)
  </Accordion>

  <Accordion title="Image too small">
    The widget doesn't inject on images smaller than 150px wide to avoid cluttering
    thumbnails. Ensure your main product image is at least 150px wide.
  </Accordion>

  <Accordion title="Check the console for errors">
    Look for `[TryOnWidget]` messages in your browser console. Error messages
    will indicate what went wrong.
  </Accordion>
</AccordionGroup>

## Button appears in the wrong position

<AccordionGroup>
  <Accordion title="Button appears below the image or misaligned">
    This happens when your image container is wider than the image itself.

    **CSS fix:**

    ```css theme={"dark"}
    .your-product-image-container {
      width: fit-content;
    }
    ```

    **Manual positioning:**

    ```css theme={"dark"}
    #tryon-trigger-host {
      margin-top: 12px;
    }
    ```
  </Accordion>

  <Accordion title="Multiple buttons appear">
    Your selector matches more than one image. Restrict to the first:

    ```js theme={"dark"}
    productSelector: '.product__media:first-child img'
    ```
  </Accordion>
</AccordionGroup>

## Image quality issues

* Use photos minimum 500×500px
* Ensure good lighting in customer photos
* Use product images with clean backgrounds

## Still stuck?

<Card title="Book a 15-min debug call" icon="calendar" href="https://calendly.com/wearo/integration">
  We'll diagnose the issue live on your store.
</Card>

Or email us at [support@wearo.io](mailto:support@wearo.io) with your store URL and a screenshot of the browser console.