Erreurs

Chaque erreur, sur l'ensemble de l'API, utilise une seule enveloppe, de sorte que vous pouvez gérer les échecs avec un seul chemin de code.

Forme de l'erreur

enveloppe d'erreur

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request was invalid.",
    "details": [
      { "path": "declaredNumber", "message": "must be E.164" }
    ]
  }
}

Le statut HTTP correspond au code. details n'est présent que pour les erreurs de validation.

Codes d'erreur

Code	HTTP	Quand
UNAUTHORIZED	401	Clé manquante ou invalide.
FORBIDDEN	403	La clé n'a pas la portée requise.
NOT_FOUND	404	Aucune ressource de ce type sur votre compte.
VALIDATION_FAILED	400	Le corps ou la requête était invalide.
CONFLICT	409	L'action entre en conflit avec l'état actuel (par ex. envoyer depuis un numéro non connecté).
RATE_LIMITED	429	Trop de requêtes. Ralentissez et réessayez.
OUTBOUND_LIMIT	429	Le plafond des envois à froid : ce numéro a lancé trop de NOUVELLES conversations cette heure-ci. Les réponses ne sont jamais comptées. Attendez la durée indiquée par Retry-After, et gardez un volume de premiers contacts modéré.
SLOT_REQUIRED	402	Connecter un numéro exige un slot libre.
ACCOUNT_SUSPENDED	402	Tout le compte est en attente. Toutes les routes répondent ainsi, sauf la connexion et la facturation. La clé est valide et réessayer n'y changera rien : contactez-nous pour rétablir l'accès.
TRANSPORT_UNAVAILABLE	503	Le service de connexion est brièvement indisponible. Réessayez sous peu.
TRANSPORT_BUSY	503	Le service de messagerie est occupé. Attendez la durée indiquée par l'en-tête Retry-After, puis réessayez ; tout ce qui a déjà été émis reste valide.
BILLING_UNAVAILABLE	503	Ce déploiement n'a aucun prestataire de paiement configuré.
INTERNAL	500	Une erreur inattendue de notre côté.

Temporiser

Trois codes vous demandent d'attendre, et ils ne veulent pas dire la même chose. RATE_LIMITED signifie ralentissez. OUTBOUND_LIMIT signifie cessez un moment d'écrire à de nouvelles personnes : les réponses passent toujours, et le budget appartient au numéro plutôt qu'à votre clé. TRANSPORT_BUSY signifie que le service de messagerie nous bride : c'est de la charge, jamais un défaut de votre requête, et tout ce qui a déjà été émis reste valide. Les trois portent Retry-After en secondes lorsque l'attente est connue ; attendez au moins ce délai.

429 Too Many Requests

{
  "error": {
    "code": "OUTBOUND_LIMIT",
    "message": "This number has started too many new conversations in the last hour."
  }
}

Erreurs de validation

Pour une erreur VALIDATION_FAILED, details liste chaque champ fautif par path, afin que vous puissiez signaler le problème à côté du bon champ.

gestion des erreurs

const res = await fetch("https://api.sendveo.com/v1/numbers", options)
if (!res.ok) {
  const { error } = await res.json()
  if (error.code === "VALIDATION_FAILED") {
    for (const d of error.details ?? []) showFieldError(d.path, d.message)
  } else {
    showBanner(error.message)
  }
}