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.
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:
{
"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 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:
{
"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:
{
"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:
{
"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 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,422reason or429. 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.