# Statuts

> Les quatre valeurs de enrichment.status, ce que chacune garantit sur merchant, la liste fermée des raisons de enrichment.reason, et la différence entre un statut et un code HTTP.

Une réponse `200` porte toujours un `enrichment.status`. C'est le champ à lire en premier : il dit ce que le moteur a répondu, et ce que vous pouvez faire de `merchant`.

## Les quatre statuts

| Statut | Signification | `merchant` | `reason` | Facturation |
|---|---|---|---|---|
| `resolved` | Identité complète et au-dessus du seuil de la politique de résolution | objet complet | `null` | 1 unité |
| `partial` | Une identité existe, mais il lui manque un élément requis ou sa confiance est sous le seuil | objet incomplet ou peu sûr | une raison | non facturé |
| `not_found` | Le moteur a répondu, et sa réponse est « personne » | `null` | `no_usable_merchant_identity` | non facturé |
| `refresh_recalculated` | Un rafraîchissement a abouti à une identité complète | objet complet | `null` | 1 unité |

`refresh_recalculated` est le pendant de `resolved` pour un rafraîchissement ; un rafraîchissement qui n'aboutit pas rend `partial` ou `not_found`.

Un cas sort de ces quatre valeurs : l'`enrichment_id` porté par une `503 engine_error` désigne la tentative échouée, et un `GET` sur lui rend `200` avec `merchant: null` et `enrichment.status: "engine_error"`. Rien n'a été facturé.

## Ce que garantit chaque statut

- **`resolved` et `refresh_recalculated`** : sous la politique de résolution en vigueur, `merchant.name` et `merchant.category` sont présents et la confiance a atteint le seuil. `logo_url` et `location` restent facultatifs.
- **`partial`** : `merchant` n'est pas `null` et porte toujours un `name`. Un champ requis peut manquer (`category`, le plus souvent), ou la confiance est sous le seuil.
- **`not_found`** : `merchant` vaut `null`. Ce n'est ni une erreur ni un échec : c'est une réponse complète. Voir [not_found](https://developer.noryo.app/fr-FR/merchant/results/not-found).

Le seuil appartient à la politique de résolution de Noryo ; il ne fait pas partie du contrat de l'API.

## Les raisons (`enrichment.reason`)

`reason` vaut `null` pour `resolved` et `refresh_recalculated`. Pour les autres statuts, il prend une valeur d'une liste fermée :

| `reason` | Statut | Signification |
|---|---|---|
| `no_usable_merchant_identity` | `not_found` | Aucune identité marchande exploitable |
| `missing_required_fields` | `partial` | Un champ requis par la politique manque |
| `confidence_below_threshold` | `partial` | La confiance est sous le seuil de la politique |
| `logo_required` | `partial` | La politique exige un logo et il manque |
| `location_required` | `partial` | La politique exige une localisation et elle manque |
| `policy_not_calibrated` | `partial` | La politique n'a pas de seuil calibré |
| `unspecified` | `partial` | Aucune des raisons ci-dessus |

La politique en vigueur n'exige ni logo ni localisation et porte un seuil calibré : en pratique, un `partial` rend aujourd'hui `missing_required_fields` ou `confidence_below_threshold`. Traitez toute valeur inconnue comme `unspecified`.

## Statut et code HTTP : deux questions

| Ce que vous recevez | Ce que cela veut dire |
|---|---|
| `200` avec `status: not_found` | Le moteur a répondu : personne. Résultat normal, non facturé. |
| `404 enrichment_not_found` | L'`enrichment_id` demandé n'existe pas pour vous. Ce n'est pas un résultat. |
| `503 engine_error` | Le moteur n'a **pas** répondu. Rien n'est facturé ni mémorisé ; reprenez. |

Un `not_found` est un résultat réglé, mémorisé, et rendu à nouveau si la même transaction est renvoyée. Un `503` n'est rien de tout cela.

## Lire un statut dans votre code

```ts
switch (body.enrichment.status) {
  case "resolved":
  case "refresh_recalculated":
    return useMerchant(body.merchant);              // identité complète
  case "partial":
    return reviewOrShowCautiously(body.merchant, body.enrichment.reason);
  case "not_found":
    return showRawDescriptor();                      // aucune identité, ce n'est pas une erreur
  default:
    return showRawDescriptor();                      // valeur inattendue : prudence
}
```

---

Page canonique : https://developer.noryo.app/fr-FR/merchant/enrichments/statuses