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

# Erreurs

> Format des erreurs, codes renvoyés, et pourquoi le 401 ne dit rien.

Toutes les erreurs partagent la même forme :

```json theme={null}
{
  "statusCode": 401,
  "message": "Clé d’API invalide.",
  "error": "UNAUTHORIZED",
  "path": "/v1/companies",
  "timestamp": "2026-08-25T09:14:02.518Z"
}
```

| Champ        | Contenu                                                                                                  |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| `statusCode` | Code HTTP, identique à celui de la réponse                                                               |
| `message`    | Message lisible, en français. **Ne le testez pas dans votre code** : il peut être reformulé sans préavis |
| `error`      | Nom symbolique du statut HTTP                                                                            |
| `path`       | Chemin appelé                                                                                            |
| `timestamp`  | Instant de l'erreur, ISO 8601 — à citer au support                                                       |

Branchez votre logique sur `statusCode`, jamais sur `message`.

## Codes renvoyés

<ResponseField name="400 — Bad Request" type="Paramètre invalide">
  Un paramètre de requête est hors bornes ou mal typé : `limit` supérieur à
  200, `offset` négatif, valeur non numérique. Les paramètres inconnus sont
  également refusés plutôt qu'ignorés — une faute de frappe dans un nom de
  paramètre est signalée au lieu de produire silencieusement un résultat non
  filtré.
</ResponseField>

<ResponseField name="401 — Unauthorized" type="Authentification refusée">
  Voir la section ci-dessous : plusieurs causes distinctes produisent cette
  même réponse.
</ResponseField>

<ResponseField name="404 — Not Found" type="Ressource absente">
  L'identifiant demandé n'existe pas, **ou** appartient à un autre workspace
  que celui de votre clé. Ces deux cas ne sont pas distingués : les distinguer
  permettrait de tester l'existence d'un identifiant chez un autre client.
</ResponseField>

<ResponseField name="429 — Too Many Requests" type="Limite de débit">
  Voir [Limites de débit](/limites-de-debit). L'en-tête `Retry-After` indique
  le délai d'attente.
</ResponseField>

<ResponseField name="500 — Internal Server Error" type="Incident">
  Une erreur de notre côté. La requête peut être rejouée. Si elle persiste,
  transmettez au support le `timestamp` et le `path` de la réponse.
</ResponseField>

## Pourquoi le `401` ne dit pas ce qui a échoué

Cinq situations différentes renvoient exactement la même réponse :

<CardGroup cols={2}>
  <Card title="En-tête absent" icon="circle-xmark" />

  <Card title="Clé inconnue" icon="circle-xmark" />

  <Card title="Clé révoquée" icon="circle-xmark" />

  <Card title="Offre insuffisante" icon="circle-xmark" />

  <Card title="Workspace suspendu" icon="circle-xmark" />
</CardGroup>

C'est un choix délibéré. Distinguer « clé inconnue » de « clé révoquée »
indiquerait à qui balaye des valeurs au hasard lesquelles ont existé ; répondre
« offre insuffisante » confirmerait qu'une clé est valide. Le refus est donc
uniforme.

<Tip>
  **Comment diagnostiquer, en pratique.** Appelez `GET /v1/me` avec la clé.

  * Réponse `200` : la clé est bonne, le problème est ailleurs — vérifiez
    l'URL et les paramètres de l'appel qui échoue.
  * Réponse `401` : ouvrez le panneau des clés dans **Administration →
    Tracking**. Si la clé y figure comme active, le blocage vient de l'offre
    ou de l'état de facturation du workspace, pas de la clé.
</Tip>

## Ce qu'une erreur ne laisse jamais derrière elle

L'API est en lecture seule : aucun code d'erreur ne correspond à une opération
partiellement appliquée. Toute requête en échec peut être rejouée telle quelle,
sans risque de doublon.