# Statuses

> The four values of enrichment.status, what each one guarantees about merchant, the closed list of enrichment.reason values, and the difference between a status and an HTTP code.

A `200` response always carries an `enrichment.status`. Read it first: it says what the engine answered, and what you can do with `merchant`.

## The four statuses

| Status | Meaning | `merchant` | `reason` | Billing |
|---|---|---|---|---|
| `resolved` | Identity complete and above the resolution policy's threshold | complete object | `null` | 1 unit |
| `partial` | An identity exists, but a required element is missing or its confidence is below the threshold | incomplete or uncertain object | a reason | not billed |
| `not_found` | The engine answered, and its answer is "nobody" | `null` | `no_usable_merchant_identity` | not billed |
| `refresh_recalculated` | A refresh produced a complete identity | complete object | `null` | 1 unit |

`refresh_recalculated` is the refresh counterpart of `resolved`; a refresh that does not succeed returns `partial` or `not_found`.

One case falls outside these four values: the `enrichment_id` carried by a `503 engine_error` designates the failed attempt, and a `GET` on it returns `200` with `merchant: null` and `enrichment.status: "engine_error"`. Nothing was billed.

## What each status guarantees

- **`resolved` and `refresh_recalculated`**: under the resolution policy in force, `merchant.name` and `merchant.category` are present and the confidence reached the threshold. `logo_url` and `location` remain optional.
- **`partial`**: `merchant` is not `null` and always carries a `name`. A required field may be missing (most often `category`), or the confidence is below the threshold.
- **`not_found`**: `merchant` is `null`. It is neither an error nor a failure: it is a complete answer. See [not_found](https://developer.noryo.app/en-GB/merchant/results/not-found).

The threshold belongs to Noryo's resolution policy; it is not part of the API contract.

## The reasons (`enrichment.reason`)

`reason` is `null` for `resolved` and `refresh_recalculated`. For the other statuses, it takes a value from a closed list:

| `reason` | Status | Meaning |
|---|---|---|
| `no_usable_merchant_identity` | `not_found` | No usable merchant identity |
| `missing_required_fields` | `partial` | A field required by the policy is missing |
| `confidence_below_threshold` | `partial` | The confidence is below the policy's threshold |
| `logo_required` | `partial` | The policy requires a logo and it is missing |
| `location_required` | `partial` | The policy requires a location and it is missing |
| `policy_not_calibrated` | `partial` | The policy has no calibrated threshold |
| `unspecified` | `partial` | None of the above |

The policy in force requires neither a logo nor a location and carries a calibrated threshold: in practice, a `partial` currently returns `missing_required_fields` or `confidence_below_threshold`. Treat any unknown value as `unspecified`.

## Status and HTTP code: two questions

| What you receive | What it means |
|---|---|
| `200` with `status: not_found` | The engine answered: nobody. A normal result, not billed. |
| `404 enrichment_not_found` | The requested `enrichment_id` does not exist for you. It is not a result. |
| `503 engine_error` | The engine did **not** answer. Nothing is billed or memorised; retry. |

A `not_found` is a settled result, memorised, and returned again if the same transaction is sent again. A `503` is none of these.

## Reading a status in your code

```ts
switch (body.enrichment.status) {
  case "resolved":
  case "refresh_recalculated":
    return useMerchant(body.merchant);              // complete identity
  case "partial":
    return reviewOrShowCautiously(body.merchant, body.enrichment.reason);
  case "not_found":
    return showRawDescriptor();                      // no identity, not an error
  default:
    return showRawDescriptor();                      // unexpected value: be cautious
}
```

---

Canonical page: https://developer.noryo.app/en-GB/merchant/enrichments/statuses