> ## Documentation Index
> Fetch the complete documentation index at: https://doc.fluximmo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Codes d'erreur

> Format de réponse erreur Fluximmo + tableau des codes principaux + comment les corriger.

L'API Fluximmo renvoie deux familles de codes : les **codes HTTP standards** (statut transport) et les **codes applicatifs Fluximmo** (raison métier précise).

## Format de réponse erreur

Toutes les erreurs métier suivent la même enveloppe JSON :

```json theme={null}
{
  "error": {
    "message": "Description lisible de l'erreur",
    "code": 10002
  }
}
```

<Note>
  Le champ `error.code` est un entier stable. Codez votre logique de retry/alerting sur ce code, pas sur le `message` (qui peut évoluer).
</Note>

## Codes applicatifs Fluximmo

| Code    | Sens                        | Cause typique                                                                       | Comment corriger                                                                                          |
| ------- | --------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `10001` | Auth invalid / missing      | Header `x-api-key` absent, mal orthographié, ou clé révoquée / expirée              | Vérifier le header (casse exacte) et la validité de la clé sur [my.fluximmo.io](https://my.fluximmo.io)   |
| `10002` | Request invalid / malformed | Body JSON invalide, champ obligatoire manquant, type incorrect                      | Valider le payload contre le DTO. Voir [`/llms-context`](/llms-context) pour copier le schéma à votre LLM |
| `10003` | Proto syntax error          | Structure du payload non conforme (ex : array au lieu d'objet, `search` mal wrappé) | Vérifier le wrapper (`search.filterProperty`, `search.filterAd`…) et la profondeur des objets nested      |

## Codes HTTP standards

| HTTP  | Sens              | Action conseillée                                                                                           |
| ----- | ----------------- | ----------------------------------------------------------------------------------------------------------- |
| `200` | OK                | Traiter la réponse                                                                                          |
| `400` | Bad Request       | Erreur côté appelant — voir `error.code` pour le détail. **Ne pas retry**                                   |
| `401` | Unauthorized      | Clé manquante ou invalide (souvent associé à `10001`). **Ne pas retry**                                     |
| `403` | Forbidden         | Endpoint non activé sur votre clé. Voir [capabilities sur demande](/api-reference/capabilities-sur-demande) |
| `404` | Not Found         | Ressource (`flxId`, alerte) inexistante ou supprimée                                                        |
| `429` | Too Many Requests | Rate limit. Respecter `Retry-After` si présent, sinon backoff exponentiel + jitter                          |
| `5xx` | Server Error      | Erreur serveur. Retry avec backoff exponentiel (max 3-5 tentatives)                                         |

## Exemple de gestion d'erreur

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time

  def call_fluximmo(url, payload, api_key, max_retries=3):
      for attempt in range(max_retries):
          r = requests.post(url, json=payload, headers={"x-api-key": api_key})

          if r.status_code == 200:
              return r.json()

          # Erreurs métier — pas de retry
          if r.status_code in (400, 401, 403, 404):
              err = r.json().get("error", {})
              raise ValueError(f"Fluximmo error {err.get('code')}: {err.get('message')}")

          # Rate limit — respecter Retry-After
          if r.status_code == 429:
              wait = int(r.headers.get("Retry-After", 2 ** attempt))
              time.sleep(wait)
              continue

          # 5xx — backoff exponentiel
          if r.status_code >= 500:
              time.sleep(2 ** attempt)
              continue

      r.raise_for_status()
  ```

  ```javascript Node.js theme={null}
  async function callFluximmo(url, payload, apiKey, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const r = await fetch(url, {
        method: "POST",
        headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
        body: JSON.stringify(payload),
      });

      if (r.ok) return r.json();

      if ([400, 401, 403, 404].includes(r.status)) {
        const { error } = await r.json();
        throw new Error(`Fluximmo error ${error.code}: ${error.message}`);
      }

      if (r.status === 429) {
        const wait = Number(r.headers.get("Retry-After") ?? 2 ** attempt);
        await new Promise((res) => setTimeout(res, wait * 1000));
        continue;
      }

      if (r.status >= 500) {
        await new Promise((res) => setTimeout(res, 2 ** attempt * 1000));
        continue;
      }
    }
    throw new Error("Max retries exceeded");
  }
  ```
</CodeGroup>

<Info>
  Voir aussi [Bonnes pratiques](/ressources/bonnes-pratiques#retry-cote-client-request) pour les patterns de retry recommandés.
</Info>