Erreurs

SIP Caller utilise les codes de statut HTTP standard pour indiquer si une requête a réussi. Les codes de la plage 2xx indiquent un succès, les codes de la plage 4xx indiquent un problème dans la requête (par exemple, un champ manquant ou un enregistrement qui n’existe pas), et les codes de la plage 5xx indiquent un problème du côté de SIP Caller.

Format des réponses d’erreur

Les réponses d’erreur ont un corps JSON conforme à la norme Problem Details :

Champ	Description
type	Une URL identifiant le type d’erreur, basée sur le code de statut HTTP.
title	Un résumé court et générique de l’erreur.
status	Le code de statut HTTP.
detail	Une explication lisible de cette erreur spécifique. Absent dans les erreurs de validation.
instance	Le chemin de la requête à l’origine de l’erreur.
traceId	Un identifiant unique de la requête. Incluez-le lorsque vous contactez le support au sujet d’une erreur.
errors	Uniquement dans les erreurs 400 et 409 : la liste des messages pour chaque champ invalide, comme décrit ci-dessous.

Les messages detail et errors sont destinés à aider les développeurs à comprendre le problème. Ne les analysez pas dans votre code, car leur texte peut changer : utilisez plutôt le code de statut HTTP.

Erreurs de validation

Lorsqu’un ou plusieurs champs de la requête sont invalides, l’API renvoie une erreur 400 Bad Request avec un objet errors. Chaque clé est le nom d’un champ invalide (avec des points pour les champs imbriqués), et chaque valeur est la liste des problèmes détectés :

Tous les champs invalides sont signalés en une seule fois, ce qui vous permet de les corriger en une seule étape. Les erreurs dans les paramètres de requête filter, sort et range sont signalées de la même manière, sous ces clés.

Codes de statut HTTP

Code	Signification
200 OK	La requête a réussi.
201 Created	La ressource a été créée. La réponse contient la nouvelle ressource.
400 Bad Request	La requête est invalide : un champ obligatoire est manquant, une valeur a un format incorrect ou est hors limites, ou le JSON est mal formé. Consultez le champ errors ou detail.
401 Unauthorized	Aucune clé API valide n’a été fournie. Consultez Authentification.
403 Forbidden	La clé API n’a pas l’autorisation d’effectuer l’opération.
404 Not Found	La ressource n’existe pas, ou n’appartient pas au compte.
408 Request Timeout	Le corps de la requête a été envoyé trop lentement.
409 Conflict	La requête entre en conflit avec l’état actuel de la ressource. Par exemple, un nom qui doit être unique est déjà utilisé, ou une ressource ne peut pas être supprimée car elle est en cours d’utilisation.
412 Precondition Failed	La ressource a été modifiée par quelqu’un d’autre depuis votre dernière lecture. Consultez Modifications simultanées ci-dessous.
413 Payload Too Large	Le corps de la requête dépasse la taille maximale de 20 Mo.
429 Too Many Requests	Trop de requêtes ont été envoyées en peu de temps. Consultez Limites de débit.
500 Internal Server Error	Un problème est survenu du côté de SIP Caller. Notre équipe est notifiée automatiquement. Vous pouvez réessayer la requête plus tard.

Modifications simultanées

Pour éviter que des modifications ne soient perdues lorsque la même ressource est modifiée en même temps par différents utilisateurs ou applications, les requêtes de modification (par exemple Modifier une campagne) exigent un champ lastUpdatedAt. Il doit contenir la valeur updatedAt de la ressource, telle que renvoyée la dernière fois que vous l’avez récupérée, créée ou modifiée.

Si la ressource a été modifiée entre-temps, sa valeur updatedAt ne correspond plus, et la modification est rejetée avec une erreur 412 Precondition Failed :

Lorsque vous recevez cette erreur, récupérez à nouveau la ressource, appliquez vos modifications à la dernière version, et renvoyez la modification avec la nouvelle valeur lastUpdatedAt.

Gérer les erreurs

Nous vous recommandons l’approche suivante dans votre intégration :

• Erreurs 4xx (sauf 429) : ne réessayez pas la même requête, car elle échouera à nouveau. Journalisez la réponse, y compris le traceId, et corrigez la requête.
• Erreurs 429 : attendez le nombre de secondes indiqué dans l’en-tête Retry-After, puis réessayez.
• Erreurs 5xx et erreurs réseau : réessayez avec un délai exponentiel (par exemple, après 1, 2, 4 et 8 secondes). Soyez prudent lorsque vous réessayez des requêtes qui créent des ressources ou ajoutent des numéros, car la première tentative a pu réussir avant l’erreur : vérifiez l’état actuel avant de réessayer.