Comprendre et traiter les erreurs de l'API

L'API publique CaptainDNS retourne toutes ses erreurs dans une enveloppe JSON standardisée. Cette page liste les codes canoniques, leur signification et l'action corrective recommandée.

Enveloppe standard

Toute réponse d'erreur suit ce format :

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota reached for the current plan",
  "details": {
    "tier": "starter",
    "limit": 50000,
    "current": 50000
  },
  "request_id": "req_a1b2c3d4"
}

code : chaîne stable documentée ici. Utilisez-le pour brancher votre logique de traitement d'erreur.
message : description lisible en anglais. Ne la parsez pas ; elle peut évoluer.
details : objet optionnel avec contexte spécifique au code. Son schéma varie par code.
request_id : identifiant CaptainDNS de la requête, utile pour ouvrir un ticket support.

Le status HTTP accompagne toujours le code. Un client robuste branche sur le couple (status, code) et traite code en priorité.

Codes d'authentification (401)

INVALID_API_KEY

Status : 401.

Cause : header Authorization manquant, préfixe absent, clé malformée ou secret altéré.

Action : vérifiez que le header est bien Authorization: Bearer cdns_live_.... Un espace parasite, un saut de ligne ou une clé tronquée sont les causes les plus fréquentes.

EXPIRED_API_KEY

Status : 401.

Cause : la clé a dépassé son expires_at.

Action : créez une nouvelle clé avec une date d'expiration plus lointaine ou sans expiration. Les clés sans expires_at sont valables tant qu'elles ne sont pas révoquées.

REVOKED_API_KEY

Status : 401.

Cause : la clé a été révoquée, soit manuellement, soit automatiquement (détection de fuite, fin de grace period de rotation).

Action : utilisez la clé active. Si vous n'en avez pas, créez-en une depuis le dashboard.

Codes d'autorisation (403)

INSUFFICIENT_SCOPE

Status : 403.

Cause : la clé n'a pas le scope requis par l'endpoint.

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Endpoint requires scope 'web:read'",
  "details": {
    "required": "web:read",
    "granted": ["dns:read", "mail:read"]
  }
}

Action : créez une nouvelle clé avec le scope manquant ou utilisez une clé qui le porte déjà. Les scopes ne sont pas modifiables après la création.

IP_NOT_ALLOWED

Status : 403.

Cause : la clé a une IP allowlist et l'IP de la requête n'en fait pas partie.

{
  "code": "IP_NOT_ALLOWED",
  "message": "Source IP not in the allowlist for this API key",
  "details": {
    "detected_ip": "203.0.113.42",
    "allowlist": ["4.175.114.0/23"]
  }
}

Action : ajoutez votre IP à l'allowlist de la clé, ou bien routez votre trafic via un egress autorisé (proxy, NAT). Vérifiez aussi que votre reverse proxy propage bien X-Forwarded-For.

QUOTA_EXCEEDED

Status : 403.

Cause : le quota mensuel de crédits est atteint et le plan n'autorise pas l'overage (plan Free).

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota reached",
  "details": {
    "tier": "free",
    "limit": 500,
    "current": 500,
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-05-01T00:00:00Z"
  }
}

Action : patientez jusqu'à la prochaine période ou passez au plan supérieur. Le dashboard CaptainDNS permet de changer de plan en un clic.

Codes de conflit (409)

IDEMPOTENCY_CONFLICT

Status : 409.

Cause : une clé Idempotency-Key est réutilisée avec un body différent de la requête originale.

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "Idempotency key reused with a different request body",
  "details": {
    "key": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Action : générez une nouvelle clé pour la nouvelle requête, ou corrigez le client qui modifie le body entre les retries.

Codes de rate limit (429)

RATE_LIMITED

Status : 429.

Cause : le token bucket per-clé est vide ou le rate limit par IP est dépassé.

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "details": {
    "scope": "per-key",
    "retry_after_seconds": 12
  }
}

Le header Retry-After accompagne toujours ce code. Attendez la durée indiquée avant de réessayer. Voir le guide rate limiting pour les strategies de backoff.

Codes serveur (5xx)

INTERNAL_ERROR

Status : 500.

Cause : erreur inattendue côté CaptainDNS.

Action : retenez le request_id et ouvrez un ticket support. Retentez dans quelques minutes : une partie de ces erreurs est transitoire (depedance backend redemarrant, bug fugitif). Si le taux dépassé 1 %, contactez l'équipe CaptainDNS.

SERVICE_UNAVAILABLE

Status : 503.

Cause : le sous-système requis par l'endpoint est temporairement indisponible.

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Public API is temporarily unavailable"
}

Action : respectez le header Retry-After s'il est présent. Si l'erreur persiste au-delà de quelques minutes, contactez le support. Les incidents sont annoncés sur le canal de statut officiel.

Codes de validation (400)

L'API retourne aussi des 400 BAD_REQUEST pour les erreurs de validation spécifiques à chaque endpoint. Ces erreurs ne sont pas couvertes par l'enveloppe standardisée ci-dessus car leur structure varie selon l'endpoint.

Exemple pour un DNS resolve avec domaine invalide :

{
  "error": "invalid domain: must be a valid FQDN",
  "field": "domain"
}

Pour les endpoints qui retournent des erreurs de validation, consultez la référence OpenAPI qui documente les schémas exacts.

Table synthetique

Status	Code	Description	Action
400	Varies	Erreur de validation	Corriger le body de la requête
401	`INVALID_API_KEY`	Clé absente ou malformée	Vérifier le header `Authorization`
401	`EXPIRED_API_KEY`	Clé expirée	Créer une nouvelle clé
401	`REVOKED_API_KEY`	Clé révoquée	Utiliser une clé active
403	`INSUFFICIENT_SCOPE`	Scope manquant sur la clé	Créer une clé avec le bon scope
403	`IP_NOT_ALLOWED`	IP hors allowlist	Ajouter l'IP ou passer par un egress autorisé
403	`QUOTA_EXCEEDED`	Quota mensuel atteint	Attendre ou upgrader le plan
409	`IDEMPOTENCY_CONFLICT`	Même clé avec body différent	Générer une nouvelle clé
429	`RATE_LIMITED`	Rate limit dépassé	Attendre `Retry-After`
500	`INTERNAL_ERROR`	Erreur serveur	Retenter + ouvrir ticket si persistant
503	`SERVICE_UNAVAILABLE`	Dépendance indisponible	Attendre, vérifier le statut

Bonnes pratiques de handling

Branchez sur le couple (status, code). Le status seul ne suffit pas : deux 403 peuvent venir de INSUFFICIENT_SCOPE ou de IP_NOT_ALLOWED, qui méritent des actions différentes.
Journalisez le request_id. C'est l'identifiant unique de la requête côté CaptainDNS et il est requis pour toute investigation côté support.
Ne retentez pas aveuglément. Les 4xx à l'exception de 429 indiquent un problème côté client : retenter sans changement n'aboutira pas.
Respectez Retry-After. Les 429 et 503 l'incluent systématiquement. Ne le court-circuitez pas.
Alertez sur les taux d'erreur. 1 % de 5xx sur une fenêtre de 5 minutes est un signal d'incident. Remontez-le dans votre observabilité.

Passez à la référence OpenAPI pour explorer les schémas endpoint par endpoint, ou revenez au quickstart si vous voulez relancer depuis le début.