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

# Erreurs et débit

> Corps d'erreur normalisé, identifiant de requête, rate-limit, idempotence.

Toutes les erreurs JSON ont la même forme :

```json theme={null}
{
  "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) |

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Trop de requêtes"
  },
  "request_id": "…"
}
```

## Idempotence

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

```http theme={null}
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.

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.