> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/fr/docs/error-codes

# Codes d'erreur

Consultez la documentation de l'API Codes d'erreur, ses paramètres de requête, les champs de réponse, les exemples de code et la gestion des erreurs pour les intégrations DomScan.

### Erreurs structurées

Chaque erreur de l’API renvoie la même structure JSON : un objet `error` avec un `code` stable, un `message` lisible, son `type` et son `status` HTTP, l’indication `retryable`, le `request_id` et une `docs_url`. Le `request_id` correspond toujours à l’en-tête de réponse `X-Request-Id` ; indiquez-le donc lorsque vous contactez le support.

```json
{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Format de domaine invalide",
    "suggestion": "Utilisez un domaine enregistrable, comme example.com",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}
```

### Champs d’erreur

| Champ | Description |
| --- | --- |
| `code` | Code d’erreur stable et lisible par une machine. Les codes ne sont jamais renommés, vous pouvez donc vous appuyer dessus en toute sécurité dans votre logique de traitement. |
| `message` | Explication lisible de l’erreur. Le libellé peut changer, ne l’analysez donc pas dans votre code. |
| `type` | Grande catégorie d’erreur, comme `validation_error`, `authentication_error` ou `rate_limit_error`. |
| `status` | Le code de statut HTTP, repris dans le corps pour les journaux et les files d’attente. |
| `retryable` | Indique si la même requête peut aboutir si vous la renvoyez plus tard. |
| `request_id` | Identifiant unique de la requête. Correspond à l’en-tête `X-Request-Id`. |
| `docs_url` | Lien vers la section de la documentation qui explique cette erreur. |
| `suggestion` | Conseil facultatif pour corriger la requête. |
| `details` | Contexte structuré facultatif, comme les méthodes autorisées ou le paramètre invalide. |
| `retry_after` | Nombre de secondes facultatif à attendre avant de réessayer. Également envoyé dans l’en-tête `Retry-After`. |

### Codes d’erreur courants

Ce sont les codes que la plupart des clients doivent gérer. Certains endpoints renvoient des codes plus spécifiques qui suivent les mêmes règles ; la liste complète avec statut, type et comportement de nouvelle tentative figure dans la spécification OpenAPI, sous `x-domscan-error-codes`. `RATE_LIMIT_EXCEEDED` reste accepté comme alias de `RATE_LIMITED`.

| Code | Statut HTTP | Type | Réessayable | Description |
| --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `validation_error` | Non | Paramètres manquants ou invalides |
| `MISSING_PARAMETER` | 400 | `validation_error` | Non | Un paramètre obligatoire est manquant |
| `INVALID_PARAMETER` | 400 | `validation_error` | Non | Un paramètre a une valeur invalide |
| `INVALID_JSON` | 400 | `validation_error` | Non | Le corps de la requête n’est pas un JSON valide |
| `INVALID_DOMAIN` | 400 | `validation_error` | Non | Format de domaine invalide |
| `UNSUPPORTED_TLD` | 400 | `validation_error` | Non | TLD non pris en charge |
| `SUBDOMAIN_NOT_SUPPORTED` | 400 | `validation_error` | Non | Cet endpoint accepte les domaines enregistrables, pas les sous-domaines |
| `VALIDATION_ERROR` | 422 | `validation_error` | Non | La requête est bien formée mais ne peut pas être traitée |
| `AUTH_REQUIRED` | 401 | `authentication_error` | Non | Aucune clé d’API ni session n’a été fournie |
| `INVALID_API_KEY` | 401 | `authentication_error` | Non | La clé d’API est invalide ou a été révoquée |
| `INSUFFICIENT_CREDITS` | 402 | `credits_error` | Non | Votre compte n’a pas assez de crédits pour cette requête |
| `FORBIDDEN` | 403 | `permission_error` | Non | Vous n’avez pas l’autorisation d’effectuer cette action |
| `NOT_FOUND` | 404 | `not_found_error` | Non | L’endpoint ou la ressource n’existe pas |
| `METHOD_NOT_ALLOWED` | 405 | `request_error` | Non | L’endpoint existe mais n’accepte pas cette méthode HTTP. L’en-tête `Allow` liste les méthodes prises en charge. |
| `CONFLICT` | 409 | `conflict_error` | Non | La requête entre en conflit avec l’état actuel de la ressource |
| `IDEMPOTENCY_CONFLICT` | 409 | `conflict_error` | Non | La clé d’idempotence a déjà été utilisée avec une requête différente |
| `IDEMPOTENCY_KEY_REUSED` | 422 | `validation_error` | Non | Cette `Idempotency-Key` a déjà été utilisée avec une requête différente au cours des dernières 24 heures. Utilisez une nouvelle clé pour une nouvelle requête. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | `conflict_error` | Oui | Une requête avec cette `Idempotency-Key` est encore en cours. Réessayez dans un instant pour recevoir sa réponse enregistrée. |
| `RATE_LIMITED` | 429 | `rate_limit_error` | Oui | Trop de requêtes |
| `INTERNAL` | 500 | `api_error` | Non | Erreur serveur inattendue. Si elle persiste, contactez le support en indiquant l’ID de la requête. |
| `UPSTREAM_ERROR` | 502 | `upstream_error` | Oui | Une source en amont a renvoyé une réponse inexploitable |
| `UPSTREAM_UNAVAILABLE` | 503 | `upstream_error` | Oui | Une source en amont est temporairement indisponible |
| `SERVICE_UNAVAILABLE` | 503 | `upstream_error` | Oui | Le service est temporairement indisponible |
| `TIMEOUT` | 504 | `timeout_error` | Oui | Une source en amont ou un registre n’a pas répondu à temps |

### Conseils pour les nouvelles tentatives

- Ne réessayez que lorsque `retryable` vaut `true`. Pour les erreurs de validation, d’authentification et d’autorisation, corrigez d’abord la requête.

- Lorsque `retry_after` ou l’en-tête `Retry-After` est présent, attendez au moins ce nombre de secondes avant la tentative suivante.

- Sinon, utilisez un backoff exponentiel avec jitter, par exemple 1, 2, 4 et 8 secondes, puis arrêtez-vous après quelques tentatives.

- Pour la création de lots et de tâches, envoyez un en-tête `Idempotency-Key` afin qu’une requête renvoyée ne crée jamais de tâche en double.

- Pour les autres requêtes POST qui facturent des crédits, un en-tête `Idempotency-Key` fait qu'une nouvelle tentative renvoie la réponse enregistrée au lieu de facturer à nouveau.

### Compatibilité

Depuis le 10 octobre 2026, tous les endpoints utilisent ce format. Les champs que certains endpoints renvoyaient déjà, comme `credits_remaining`, `purchase_url`, `login_url`, `success` ou `meta`, sont conservés pendant une période de compatibilité, de sorte que les intégrations existantes continuent de fonctionner. Dans le nouveau code, lisez les détails de l’erreur dans l’objet `error`.