# Errors and limits

> What a failed request looks like, the limits to design around, and what can run in a shopper's browser.

## GraphQL errors

A GraphQL request that fails still returns JSON. The problem is in an `errors` list, and `data` holds whatever could be answered, or `null`. For example, an item query sent without the shopper header:

```json
{
  "data": null,
  "errors": [
    {
      "message": "400: Solenya-User-UUID needs to be provided",
      "locations": [{ "line": 3, "column": 5 }],
      "path": ["items", "merchant_feed"]
    }
  ]
}
```

Check for `errors` on every response, not just the HTTP status. `path` says which field failed.

Errors about your request explain themselves. Some you are likely to meet:

| Message | Cause |
|---------|-------|
| `401: Invalid Authentication: We're keeping our lid sealed. Please check your token and try again!` | The `Authorization` header is missing, or the token is invalid, expired or revoked |
| `Insufficient permissions. Required any of: '...'` | The token lacks a [scope](https://solenya.ai/docs/auth.md#scopes) this field needs. The message lists the scopes that would do. |
| `400: Solenya-User-UUID needs to be provided` | An item query without the shopper header |
| `400: Invalid Solenya-User-UUID header: '...' is not a valid UUID` | The shopper header isn't a UUID |
| `400: rank_with with multimodal_query must be provided` | A `page` request with nothing to rank by |

An unexpected failure on Solenya's side is reported as `Oops! We are in a pickle, something went wrong!`, with the details kept out of the response. If it keeps happening, send Solenya the request's timestamp.

## Warnings

A request can succeed and still carry advice in `extensions.warnings`, a list of messages:

```json
{
  "data": { "items": { "merchant_feed": { "page": { "rows": [] } } } },
  "extensions": { "warnings": ["No items found for the given criteria."] }
}
```

| Warning | Means |
|---------|-------|
| `No items found for the given criteria.` | The first page came back empty, often because the filter left nothing |
| `Found 2 items, but expected 3.` | Some products in an `item` query aren't in the index |
| `score_cutoff not applied: ...` | Your request changed the search model, so the index's score cutoff no longer fits |

## Limits

| Limit | Value | What happens past it |
|-------|-------|----------------------|
| Requests | 1000 per second | `429 Too Many Requests` |
| Time to start a response | 2.2 seconds | `504 Gateway Timeout` |
| Item `page_size` | 100 | The request is rejected |
| Search `text` | 10,000 characters | The request is rejected |
| Images per search | 10 | The request is rejected |
| Products in `item.in` | 50 | The request is rejected |
| Uploaded image size | 10 MB per file | The request is rejected |
| Products in an event's `item.in_` | 50 | `422` from the tracking endpoint |

### Rate limit

Requests are counted over one-second windows, up to 1000 a second. Sign-in and token endpoints under `/v1/auth` aren't counted.

Past the limit, the API answers `429` with a `Retry-After` header in seconds:

```json
{
  "detail": "Rate limit exceeded. Please reduce request frequency.",
  "retry_after": 1
}
```

Wait for `Retry-After` before trying again, and back off further if the `429`s continue.

### Timeout

A request that hasn't started its response within 2.2 seconds gets a `504`:

```json
{
  "detail": "Request processing time exceeded limit",
  "processing_time": 2.2013,
  "internal_timeout": true
}
```

The `/v1/auth` endpoints have no such limit.

## Calling from a browser

The GraphQL API accepts cross-site browser requests only from a fixed list of origins that Solenya maintains. From any other site, a browser `fetch` to `/v1/graphql` is blocked before it is sent. Item queries also need a secret key, so send them from your backend either way.

| From the shopper's browser or app | Works? |
|-----------------------------------|--------|
| [Event tracking](https://solenya.ai/docs/track.md) with a publishable key, using `navigator.sendBeacon` or a form post | Yes. It is a plain form post, which browsers send to any site. The browser can't read the response. |
| Item queries | No. Send them from your backend with a secret API key. |

Routing item queries through your backend also keeps the secret key off the client, and lets you log requests or change them without shipping a new app.

## Debugging a request

- **Send it with curl or from your server.** Both show the full response, including any `errors`, `422` reason or `429`. A browser on your site can't read the tracking endpoint's responses.
- **Try it in the [GraphQL explorer](https://solenya.ai/docs/graphql.md#the-graphql-explorer)** after adding your headers. It checks the query against the schema as you type.
