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

# Gestion des erreurs

> Reponses d'erreur standardisees avec suggestions actionnables

Toutes les erreurs de l'API suivent un format coherent concu pour les developpeurs et les agents IA.

## Format de reponse d'erreur

```json theme={null}
{
  "error": {
    "type": "not_found_error",
    "code": "CONVERSATION_ITEM_NOT_FOUND",
    "message": "No call or message found with ID 'cll_abc123'.",
    "retryable": false,
    "request_id": "req_a1b2c3d4e5f6",
    "doc_url": "https://help.withallo.com/en/v2/api-reference/guides/error-handling#CONVERSATION_ITEM_NOT_FOUND",
    "param": "id",
    "suggestion": "Search for the item using POST /v2/api/conversations/items/search."
  }
}
```

## Champs d'erreur

| Champ                 | Type    | Description                                                                 |
| --------------------- | ------- | --------------------------------------------------------------------------- |
| `type`                | string  | Categorie d'erreur (voir tableau ci-dessous)                                |
| `code`                | string  | Code d'erreur stable pour le traitement programmatique                      |
| `message`             | string  | Explication lisible incluant la valeur en echec                             |
| `retryable`           | boolean | Indique si la requete peut etre retentee                                    |
| `request_id`          | string  | Identifiant unique de cette requete — a inclure dans les tickets de support |
| `doc_url`             | string  | Lien vers la documentation de cette erreur                                  |
| `param`               | string  | Le parametre ayant cause l'erreur (le cas echeant)                          |
| `suggestion`          | string  | Action recommandee (peut inclure des noms d'endpoints)                      |
| `errors`              | array   | Erreurs au niveau des champs pour les echecs de validation                  |
| `retry_after_seconds` | integer | Secondes a attendre avant de reessayer (rate limits uniquement)             |

## Types d'erreur

| Type                   | Code HTTP | Quand                                                   |
| ---------------------- | --------- | ------------------------------------------------------- |
| `authentication_error` | 401       | API key invalide, manquante ou expiree                  |
| `permission_error`     | 403       | Cle valide mais scope insuffisant                       |
| `validation_error`     | 400       | Entree incorrecte, parametres manquants, mauvais format |
| `not_found_error`      | 404       | La ressource n'existe pas                               |
| `conflict_error`       | 409       | Doublon ou conflit d'etat                               |
| `rate_limit_error`     | 429       | Trop de requetes (toujours `retryable: true`)           |
| `server_error`         | 500       | Erreur interne                                          |

## Request ID

Chaque reponse inclut un `request_id` (format : `req_` + 12 caracteres alphanumeriques). Vous pouvez egalement envoyer le votre via le header `X-Request-Id` — l'API l'utilisera au lieu d'en generer un.

```bash theme={null}
curl -X GET "https://api.withallo.com/v2/api/conversations" \
  -H "Authorization: Api-Key ak_live_your_key" \
  -H "X-Request-Id: req_my_custom_id"
```

## Erreurs de validation

Lorsque plusieurs champs echouent a la validation, le tableau `errors` liste chacun d'entre eux :

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "INVALID_REQUEST",
    "message": "Request validation failed.",
    "errors": [
      { "field": "date_from", "code": "INVALID_DATE", "message": "Must be a valid ISO 8601 date." },
      { "field": "allo_number", "code": "INVALID_PHONE_FORMAT", "message": "Must be E.164 format (e.g. +14155551234)." }
    ]
  }
}
```

## Format des numeros de telephone

Tous les numeros de telephone doivent etre au **format E.164** : `+` suivi du code pays et du numero, sans espaces ni tirets.

```
+14155551234    <- correct
0612345678      <- incorrect (code pays manquant)
+33 6 12 34 56  <- incorrect (contient des espaces)
```

Les numeros de telephone invalides retournent :

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "INVALID_PHONE_FORMAT",
    "message": "'+33 6 12 34' is not a valid E.164 phone number.",
    "suggestion": "Use E.164 format: +14155551234 (no spaces, with country code)."
  }
}
```

## Idempotence

Tous les endpoints d'ecriture (POST, PUT, DELETE) supportent un header optionnel `Idempotency-Key` pour reessayer les requetes en toute securite.

### Comment ca fonctionne

1. Envoyez un header `Idempotency-Key` unique avec votre requete d'ecriture (par exemple, un UUID)
2. Si la requete **reussit** (2xx), la reponse est stockee pendant **1 heure**
3. Si vous envoyez la meme cle au **meme endpoint**, l'API retourne la reponse stockee avec un header `Idempotency-Replayed: true` — l'operation n'est pas re-executee
4. Si la requete **echoue** (4xx/5xx), la cle **n'est pas consommee** — vous pouvez reessayer avec la meme cle jusqu'a ce que la requete reussisse

### Exemple

```bash theme={null}
# Premiere requete — execute l'operation
curl -X POST "https://api.withallo.com/v2/api/conversations/items/cll-abc123/tags" \
  -H "Authorization: Api-Key ak_live_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"tags": ["qualified"]}'
# -> 200 OK, Idempotency-Key: 550e8400-...

# Nouvelle tentative — retourne la reponse stockee sans re-executer
curl -X POST "https://api.withallo.com/v2/api/conversations/items/cll-abc123/tags" \
  -H "Authorization: Api-Key ak_live_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"tags": ["qualified"]}'
# -> 200 OK, Idempotency-Replayed: true
```

### Reutilisation des cles entre endpoints

Utiliser la meme cle d'idempotence pour un endpoint ou une methode HTTP differente retourne une erreur `409` avec le code `IDEMPOTENCY_KEY_REUSE`.

### Headers de reponse

| Header                 | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `Idempotency-Key`      | Renvoye sur toutes les requetes qui incluent le header         |
| `Idempotency-Replayed` | Defini a `true` lorsque la reponse est rejouee depuis le cache |

## Reference des codes d'erreur

Consultez le [catalogue des codes d'erreur](/fr/v2/api-reference/guides/error-codes) pour une liste complete de tous les codes d'erreur avec les instructions de resolution.