> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.
# What Happens When a Scan Can't Be Resolved
> How Closient handles a scan it can't match — the outcome and reason codes, how lot and serial walk-up works, the two fallback modes for your own domain, and a reference for the csi_ parameters a redirect carries.
Sooner or later someone scans a code Closient doesn't recognise. A typo in a print file, a product that was never added to your catalog, a label from a supplier, a counterfeit. None of these are rare, and each one tells you something.
This page explains what Closient does with that scan, what you can choose to do instead, and exactly what information reaches the page you send the scanner to.
## Every scan gets one outcome
Each scan of a product code ends in exactly one of six outcomes. The outcome is also the **reason code** you'll see in reports and in redirect parameters.
| Reason code | What it means | Is it a dead end? |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| `resolved` | The scan matched exactly what it asked for. | No |
| `partial` | The code carried a lot or serial number we don't have registered, so we resolved at the product level instead. See [walk-up](#lot-and-serial-walk-up). | No |
| `malformed` | The value isn't a GTIN at all: wrong length, or not all digits. | Yes |
| `invalid_checksum` | The right shape for a GTIN, but the final check digit doesn't add up. Usually a misprint or a misread. | Yes |
| `unknown_key` | A well-formed GTIN that isn't in the catalog. | Yes |
| `no_links` | A product we know, but it has nothing published for the specific link type the scan asked for. | Yes |
Only the four dead ends trigger your fallback policy. `resolved` and `partial` both put the scanner in front of a real page.
Today the outcome codes cover product (GTIN) scans. Other identifier types on the resolver, such as SSCC and GLN, are not classified this way yet.
## Lot and serial walk-up
A scan can carry more than the product. A code such as `/01/09506000134352/10/LOT9/21/SN42` names a product, a lot and a single unit.
Closient looks for the most specific thing you've registered and works back from there:
1. The serial number, if it's registered.
2. The lot, if it's registered.
3. The product.
If the scan carries a lot or serial you haven't registered, Closient doesn't fail. It walks up to the next level it does know, and the scanner lands on your product's page (or wherever your product-level, brand-level or organization-level [resolver rules](/user-guides/resolver-rules) point). That follows the GS1 Digital Link resolver standard: an unknown lot under a known product is not a missing product.
A walk-up is recorded with the reason `partial`. It is not a dead end and it never triggers your fallback policy, but it is still worth knowing about. An unregistered lot or serial can mean a lot you forgot to register, or a code that shouldn't exist.
## The two fallback modes
The fallback policy is set **per custom domain**. It applies when a scan enters through a hostname you've connected, such as `id.yourbrand.com`. Scans that come in through Closient's own domains always get the default behavior.
### Hosted 404 (default)
Closient answers with a real HTTP `404`, not a redirect. What the scanner sees depends on the reason:
| Reason | What the scanner gets |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unknown_key` | A Closient-hosted "we haven't catalogued this product yet" page, themed with your brand. It offers to notify the scanner when the product is added. Status `404`. |
| `no_links` | Status `404`. |
| `malformed`, `invalid_checksum` | Status `400`, with a short error message. |
The page is marked `noindex` and is never cached, so it can't leak one brand's theming onto another visitor's screen, and it stops appearing the moment you add the product.
### Redirect
In redirect mode, every dead end is answered with a redirect to a page on your own site. It is opt-in, and you choose the destination.
* **Always a `307`.** Never `301` or `308`. Browsers and CDNs cache permanent redirects, and a code that fails today may be a valid, registered product tomorrow. A `307` is never cached as a permanent answer.
* **The destination is yours alone.** It is set in your configuration and never taken from anything in the scan, so nobody can craft a code that sends people somewhere else through your domain. It must be an absolute `https://` URL.
* **UTM tags are added.** The defaults are `utm_source=closient`, `utm_medium=qr` and `utm_campaign=unresolved_scan`. You can override any of the five UTM fields (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`); a blank field keeps the default, and `utm_term` and `utm_content` are left out unless you set them.
* **Diagnostic parameters are added.** These are the `csi_` parameters described below, so your page can tell what failed and why.
* **Your own query parameters win.** If your destination URL already has a parameter with the same name, it is kept and Closient's version is not added.
Redirect mode covers people scanning with a phone or browser. A machine client that explicitly asks for a linkset or JSON representation of a known product keeps the standard `404` behaviour rather than being redirected.
## The `csi_` parameter reference
Every redirect carries diagnostic parameters that start with `csi_`. The prefix stands for **Closient Search Inc**. It is a namespace reserved for the platform, so it won't collide with parameters your own site uses. Don't use `csi_` names for your own tracking.
| Parameter | Value | When it's included |
| ------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `csi_reason` | The reason code: `malformed`, `invalid_checksum`, `unknown_key` or `no_links` | Always |
| `csi_gtin` | The scanned GTIN, as 14 digits | Only when the GTIN was well-formed. Never for `malformed`. |
| `csi_lot` | The scanned lot number (GS1 AI 10) | Only when a lot was present and valid: up to 20 printable characters, no spaces |
| `csi_serial` | The scanned serial number (GS1 AI 21) | Only when a serial was present and valid, under the same rules |
| `csi_path` | The path of the scanned link, for example `/01/09506000134352/10/LOT9` | Only when the path was well-formed. Never for `malformed`. |
Nothing is passed through as-is. Each value is checked before it is included, length-capped (14 characters for the GTIN, 20 for a lot or serial, 256 for the path), and URL-encoded. A value that fails its check is left out rather than cleaned up, so a garbled scan can never put arbitrary text into your URL. For a `malformed` scan the bad value is the whole problem, so `csi_gtin` and `csi_path` (which contains it) are never sent.
For an unknown product scanned on `id.yourbrand.com` with a redirect destination of `https://yourbrand.com/not-found`, your page receives something like this (parameter order isn't guaranteed):
```text theme={null}
https://yourbrand.com/not-found
?utm_source=closient
&utm_medium=qr
&utm_campaign=unresolved_scan
&csi_reason=unknown_key
&csi_gtin=09506000134352
&csi_lot=LOT9
&csi_path=%2F01%2F09506000134352%2F10%2FLOT9
```
Treat these values as information, not instructions. They come from a code someone scanned, so validate and escape them if your page displays them.
## Setting your policy
You set the policy per hostname with the custom hostname API, using an account with change permission on your organization:
```text theme={null}
POST /organizations/{organization_id}/custom-hostnames/fallback-policy
```
Send the `hostname`, the `mode` (`hosted_404` or `redirect`), and for redirect mode the `redirect_url` and any UTM overrides. If the mode is `redirect` and the URL isn't a well-formed absolute `https://` URL, the request is rejected with a `422` and nothing changes. See [API overview](/api-overview) for authentication.
There is no settings page for this yet. Until there is, the API is the way to change it.
## See what people are scanning
Every dead end and every `partial` walk-up on your custom domains is recorded, on every plan. Reading that record is a Business plan feature: the **Unresolved scans** page under Resolver lists each key with its reason, the domain it came in on, when it was first and last seen, and how many times it was scanned. For an `unknown_key` you can create the product in one click, prefilled with the scanned GTIN.
Read it as a to-do list. A GTIN that keeps showing up as `unknown_key` is a product missing from your catalog. A one-off `invalid_checksum` is a typo. A GTIN that no one at your company recognises may be a counterfeit.
Choose where a successful scan goes, by product, lot, serial or time.
The length of your resolver domain decides how big your printed QR code has to be.