Erreurs et débit

Toutes les erreurs JSON ont la même forme :

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Clé API requise"
  },
  "request_id": "8f3c1a2e-…"
}

Le header x-request-id est renvoyé sur chaque réponse (y compris les succès). En cas de support, joignez cet identifiant.

Codes fréquents

HTTP	`error.code`	Quand
400	`BAD_REQUEST`	Paramètres invalides (deux modes qualify à la fois, etc.)
400	`IDEMPOTENCY_KEY_REQUIRED`	POST facturable sans header `Idempotency-Key`
400	`IDEMPOTENCY_KEY_INVALID`	Clé d’idempotence mal formée
401	`UNAUTHORIZED`	Clé absente, invalide, révoquée ou expirée
403	`FORBIDDEN`	Scope manquant
403	`BILLING_HOLD`	Organisation en hold facturation
404	`BUILDING_NOT_FOUND`	Immeuble introuvable pour le mode d’entrée
409	`IDEMPOTENCY_CONFLICT`	Même `Idempotency-Key` encore en cours
429	`RATE_LIMIT_EXCEEDED`	Débit dépassé
501	`NOT_IMPLEMENTED`	Route hors v1

GET /v1/meta/usage reste disponible pendant un hold, pour consulter la consommation.

Rate-limit

Défaut : 60 requêtes / minute soutenues, burst 20. Un plafond plus élevé peut être posé sur la clé. Headers de réponse :

Header	Sens
`X-RateLimit-Limit`	Plafond de la fenêtre
`X-RateLimit-Remaining`	Restant
`X-RateLimit-Reset`	Epoch Unix de fin de fenêtre
`Retry-After`	Secondes avant nouvel essai (sur 429)

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Trop de requêtes"
  },
  "request_id": "…"
}

Idempotence

Les POST facturables (aujourd’hui POST /v1/contacts/find) exigent :

Idempotency-Key: <chaîne opaque, 1–256 caractères imprimables>

La première réponse est rejouée pendant 24 h pour la même clé API et la même Idempotency-Key. Le header X-Idempotency-Replayed: true signale un rejeu.

Générez un UUID v4 par intention métier (un contact à trouver), pas par retry TCP. Un timeout réseau suivi du même UUID ne double pas la facturation.

⌘I

Démarrer

Guides

Référence API

Erreurs et débit

Codes fréquents

Rate-limit

Idempotence

​Codes fréquents

​Rate-limit

​Idempotence

Codes fréquents

Rate-limit

Idempotence