Passer au contenu principal
Toutes les erreurs de l’API suivent un format coherent concu pour les developpeurs et les agents IA.

​
Format de reponse d’erreur

{
  "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

ChampTypeDescription
typestringCategorie d’erreur (voir tableau ci-dessous)
codestringCode d’erreur stable pour le traitement programmatique
messagestringExplication lisible incluant la valeur en echec
retryablebooleanIndique si la requete peut etre retentee
request_idstringIdentifiant unique de cette requete — a inclure dans les tickets de support
doc_urlstringLien vers la documentation de cette erreur
paramstringLe parametre ayant cause l’erreur (le cas echeant)
suggestionstringAction recommandee (peut inclure des noms d’endpoints)
errorsarrayErreurs au niveau des champs pour les echecs de validation
retry_after_secondsintegerSecondes a attendre avant de reessayer (rate limits uniquement)

​
Types d’erreur

TypeCode HTTPQuand
authentication_error401API key invalide, manquante ou expiree
permission_error403Cle valide mais scope insuffisant
validation_error400Entree incorrecte, parametres manquants, mauvais format
not_found_error404La ressource n’existe pas
conflict_error409Doublon ou conflit d’etat
rate_limit_error429Trop de requetes (toujours retryable: true)
server_error500Erreur 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. 
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 : 
{
  "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 : 
{
  "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

# 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

HeaderDescription
Idempotency-KeyRenvoye sur toutes les requetes qui incluent le header
Idempotency-ReplayedDefini a true lorsque la reponse est rejouee depuis le cache

​
Reference des codes d’erreur

Consultez le catalogue des codes d’erreur pour une liste complete de tous les codes d’erreur avec les instructions de resolution.