Developer docs

Errors and limits

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

View as Markdown

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:

MessageCause
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 this field needs. The message lists the scopes that would do.
400: Solenya-User-UUID needs to be providedAn item query without the shopper header
400: Invalid Solenya-User-UUID header: '...' is not a valid UUIDThe shopper header isn't a UUID
400: rank_with with multimodal_query must be providedA 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."] }
}
WarningMeans
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#

LimitValueWhat happens past it
Requests1000 per second429 Too Many Requests
Time to start a response2.2 seconds504 Gateway Timeout
Item page_size100The request is rejected
Search text10,000 charactersThe request is rejected
Images per search10The request is rejected
Products in item.in50The request is rejected
Uploaded image size10 MB per fileThe request is rejected
Products in an event's item.in_50422 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 429s 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 appWorks?
Event tracking with a publishable key, using navigator.sendBeacon or a form postYes. It is a plain form post, which browsers send to any site. The browser can't read the response.
Item queriesNo. 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 after adding your headers. It checks the query against the schema as you type.