Référence

Erreurs

Chaque erreur de l’API a un statut HTTP et un code stable. Les codes généraux peuvent venir de n’importe quel appel ; les autres sont propres à un produit.

Codes d’erreur généraux

Chaque erreur est un objet JSON plat : code, message (suit Accept-Language), messageEn, messageFr, statusCode, et un champ details facultatif précisant la cause. Une requête mal formée, comme un champ manquant ou une valeur hors des limites documentées, retourne 422 VALIDATION_ERROR avec details qui nomme le champ. Une requête que le framework rejette lui-même avant que votre code ne s’exécute, comme un JSON invalide (400), un corps dépassant la limite de taille (413) ou un type de contenu non pris en charge (415), retourne un code Fastify FST_ERR_* avec un message uniquement en anglais.

HTTP	Code	Signification
401	UNAUTHORIZED	Clé API manquante ou invalide
401	API_KEY_REVOKED	Cette clé API a été révoquée. Utilisez une autre clé.
402	INSUFFICIENT_BALANCE	Solde du compte insuffisant
402	PAYMENT_REQUIRED	Le compte n’a pas encore effectué sa première recharge. Les clés de production sont bloquées jusque-là, sauf quelques lectures de compte et de tarifs ; les clés de test ne sont pas concernées.
403	FORBIDDEN	La clé API n’a pas la permission requise, skip_consent_check a été envoyé avec une clé de production, le compte est suspendu ou fermé (voir details.reason), ou l’identifiant dans le chemin appartient à un autre compte
403	LIVE_KEY_REQUIRED	Une clé de test a été utilisée pour une action réservée aux clés de production.
403	PERMISSION_ESCALATION	Une clé nouvelle ou renouvelée a demandé des permissions plus étendues que celles de l’appelant, sans confirmation par mot de passe.
403	KEY_FENCED	Cette clé est restreinte par ses propres listes d’autorisation ou de blocage ou par le refus par défaut ; elle ne peut donc pas modifier ces listes ni les groupes et contacts qu’elles incluent, changer les réglages de listes d’une clé, créer de clés, ni renouveler une autre clé qu’elle-même.
403	ACCOUNT_NOT_VERIFIED	Le compte n’a pas encore vérifié de numéro de téléphone propriétaire, requis avant un envoi réel.
403	SENDING_PAUSED	L’envoi réel est suspendu sur ce compte (les détails indiquent la reprise et la raison)
404	NOT_FOUND	Aucune ressource ne correspond à l’identifiant donné.
409	DEAD_LETTER_ALREADY_REPLAYED	Cet événement a déjà été rejoué, ou un rejeu est en cours. Rien n’a été envoyé, et réessayer n’y changera rien.
409	CONFLICT	Une ressource avec cet identifiant existe déjà, ou le renouvellement d’une clé a échoué parce qu’elle était déjà révoquée, est une clé de session, ou qu’une autre requête l’a renouvelée en premier
422	VALIDATION_ERROR	Échec de la validation du corps ou de la requête (voir details)
422	WEBHOOK_LIMIT_REACHED	Limite de 10 points de terminaison webhook par compte atteinte. Supprimez-en un avant d’en enregistrer un autre
429	RATE_LIMITED	Trop de requêtes. Veuillez ralentir
500	INTERNAL_ERROR	Une erreur serveur inattendue s’est produite. Réessayez
502	WEBHOOK_REPLAY_FAILED	Le point de terminaison n’a pas accepté le rejeu. L’évènement reste dans la file des lettres mortes
503	SERVICE_UNAVAILABLE	Les nouvelles inscriptions sont temporairement désactivées (POST /v1/accounts), ou la vérification téléphonique est temporairement indisponible (POST /v1/accounts/:id/phone-verification). Réessayez plus tard

Les codes propres à un produit ont leurs propres sections plus bas : codes d’erreur SMS et codes d’erreur du courriel.

Codes d’erreur SMS

Les codes ci-dessous sont propres aux SMS, aux numéros de téléphone, à la vérification et à la LCAP. Tout appel peut aussi répondre avec les codes de la section générale ci-dessus, comme VALIDATION_ERROR, INSUFFICIENT_BALANCE et NOT_FOUND.

HTTP	Code	Signification
403	NUMBER_LIMIT_REACHED	Le compte a atteint sa limite de numéros de téléphone
403	PHONE_NUMBER_NOT_OWNED	Le numéro from n’est pas provisionné sur ce compte.
403	ALLOW_LIST_BLOCKED	Le destinataire ne figure pas sur la liste ALLOW de cette clé API
403	DENY_LIST_BLOCKED	Le destinataire figure sur la liste DENY de cette clé API
403	SEND_LIMIT_REQUEST_TOO_EARLY	Les demandes de volume s’ouvrent une fois la période probatoire du compte terminée.
404	VERIFICATION_NOT_FOUND	Identifiant de vérification introuvable ou non associé à ce compte
404	CONTACT_NOT_FOUND	Contact introuvable
404	CONTACT_GROUP_NOT_FOUND	Groupe de contacts introuvable
404	CONTACT_GROUP_MEMBER_NOT_FOUND	Ce contact n’est pas membre de ce groupe
404	CONTACT_LIST_NOT_FOUND	Liste de contacts introuvable
404	CONTACT_LIST_ENTRY_NOT_FOUND	Entrée de liste introuvable
409	VERIFICATION_ALREADY_VERIFIED	Ce numéro a déjà été vérifié
409	PURCHASE_IN_PROGRESS	Un autre achat de numéro est en cours. Réessayez sous peu
409	ALLOWANCE_REQUEST_PENDING	Une demande d'allocation est déjà en attente d'examen
409	PHONE_NUMBER_SUSPENDED	Les frais mensuels de ce numéro n’ont pas pu être prélevés. Rechargez votre solde pour le réactiver.
409	SEND_LIMIT_REQUEST_PENDING	Une demande de volume est déjà en attente d’examen.
409	IDEMPOTENCY_KEY_REUSED	La même clé Idempotency-Key a été envoyée avec un to, from ou body différent.
409	CONTACT_ALREADY_EXISTS	Un contact avec ce numéro de téléphone ou ce courriel existe déjà
409	CONTACT_IN_USE	Retirez le contact de ses groupes et de ses listes avant d’effacer son numéro de téléphone
409	CONTACT_GROUP_ALREADY_EXISTS	Un groupe de contacts avec ce nom existe déjà
409	CONTACT_GROUP_MEMBER_EXISTS	Le contact est déjà membre de ce groupe
409	CONTACT_LIST_ALREADY_EXISTS	Une liste de contacts avec ce nom existe déjà
409	CONTACT_LIST_ENTRY_EXISTS	Cette entrée existe déjà dans la liste
410	VERIFICATION_EXPIRED	Le code de vérification a expiré
422	NON_CANADIAN_NUMBER	Numéro E.164 canadien invalide
422	UNDELIVERABLE_NUMBER	Le numéro a échoué trois fois de suite chez l’opérateur (tous clients confondus) ; refusé sans frais pendant 90 jours.
422	NOT_A_MOBILE_NUMBER	Le numéro de destination est une ligne fixe ou un numéro VoIP. L’opérateur le refuse avant l’envoi ; rien n’est facturé.
422	RESERVED_DESTINATION	Le numéro de destination appartient à un central réservé (555-XXXX, N11, codes de test des opérateurs). Refusé avant tout envoi ; rien n’est facturé.
422	MESSAGE_TOO_LONG	Le texte dépasserait la limite de 10 parties SMS de l'opérateur (≈1 530 caractères GSM-7 ou 670 caractères Unicode). Rien n'est facturé
422	VERIFICATION_INVALID_CODE	Code incorrect. attempts_remaining indique le nombre de tentatives restantes
422	INVALID_ALLOWANCE_REQUEST	L'allocation demandée doit dépasser votre limite actuelle
422	LINK_SHORTENER_BLOCKED	Les raccourcisseurs de liens sont refusés car les opérateurs les filtrent. Utilisez l’URL complète
422	BROADCAST_TOO_LARGE	Groupe de contacts trop grand pour une seule diffusion (250 membres par défaut). Divisez-le et envoyez par lots
422	CANNOT_ERASE_OWN_NUMBER	Ce numéro appartient à votre compte. L’effacement vise uniquement le numéro d’un abonné
422	TOO_MANY_AREA_CODES	Recherchez au plus 25 indicatifs régionaux à la fois
422	INVALID_PHONE_NUMBER	Numéro de téléphone E.164 invalide
422	CONTACT_LIST_ENTRY_INVALID	Chaque entrée doit spécifier exactement l’un des champs phone_number, contact_id ou contact_group_id
422	CONTACT_HAS_NO_PHONE	Le contact n’a pas de numéro de téléphone ; il ne peut donc pas être ajouté à un groupe ou à une liste SMS
429	RECIPIENT_RATE_LIMITED	Plus de 30 messages vers un même destinataire en une heure ou 100 en une journée ; réessayez après l’en-tête Retry-After.
429	VERIFICATION_MAX_ATTEMPTS	Trop de tentatives incorrectes. Cette vérification est verrouillée
429	DAILY_LIMIT_REACHED	Limite d’envoi quotidienne atteinte (les détails indiquent votre limite et le compte). Demandez un volume plus élevé une fois admissible
429	FANOUT_LIMIT_REACHED	Ce message identique a déjà atteint le nombre maximal de destinataires distincts autorisé sur 24 heures
429	NUMBER_RATE_LIMITED	Ce numéro d’envoi a atteint sa limite par minute. Réessayez sous peu
429	BROADCAST_LIMIT_REACHED	Limite de diffusions atteinte pour ce compte au cours des 24 dernières heures
451	OPT_OUT_BLOCKED	Le destinataire s’est désabonné. L’envoi est donc bloqué par la loi.
451	NO_CONSENT	Pas de consentement LCAP valide en dossier
451	CONSENT_EXPIRED	Consentement tacite expiré (limite LCAP de 2 ans)
451	DNCL_BLOCKED	Numéro sur la LNNTE du CRTC sans exemption applicable (à venir; non retourné actuellement)
501	DNCL_COMING_SOON	La vérification de la liste nationale de numéros de télécommunication exclus du CRTC n’est pas encore disponible.
501	TOLLFREE_800_COMING_SOON	Les numéros 1-800 ne sont pas encore disponibles. Choisissez un autre préfixe sans frais ou un numéro local.
502	CARRIER_ERROR	L’opérateur a renvoyé une erreur lors de l’envoi.
502	PROVISIONING_FAILED	L’opérateur n’a pas pu compléter cet achat de numéro. Rien n’a été facturé.
502	NUMBER_SEARCH_FAILED	La recherche de numéros est temporairement indisponible.
502	RELEASE_FAILED	L’opérateur n’a pas accepté la libération. Le numéro vous appartient toujours ; réessayez sous peu
503	CARRIER_UNAVAILABLE	L’opérateur est injoignable ; rien n’a été envoyé ni facturé. Réessayez sous peu.
503	CARRIER_TIMEOUT	L’opérateur n’a pas répondu à temps : le message a peut-être été envoyé, ou non. Rien n’est facturé. Vérifiez le statut du message avant de l’envoyer de nouveau : une nouvelle tentative avec la même Idempotency-Key renvoie le message en échec au lieu de l’envoyer une seconde fois.

Codes d’erreur du courriel

Les appels de courriel peuvent aussi répondre avec les codes de la section générale ci-dessus, comme VALIDATION_ERROR, INSUFFICIENT_BALANCE et NOT_FOUND.

HTTP	Code	Signification
403	EMAIL_DOMAIN_NOT_ALLOWED	La clé API est restreinte à certains domaines d’envoi, et celui-ci n’en fait pas partie.
403	TEST_KEY_REQUIRED	Seule une clé de test peut appeler ce point de terminaison.
404	RECEIVED_EMAIL_NOT_FOUND	Aucun courriel reçu avec cet identifiant.
409	EMAIL_DOMAIN_ALREADY_EXISTS	Le domaine est déjà sur ce compte.
409	EMAIL_DOMAIN_IN_USE	Un autre compte détient ce domaine. details.retry_after indique quand une revendication non vérifiée expire ; un domaine vérifié reste à son propriétaire.
409	EMAIL_DOMAIN_HAS_INFLIGHT	Le domaine a encore des courriels en file, programmés ou en cours d’envoi.
409	EMAIL_IDEMPOTENCY_IN_PROGRESS	Une requête utilisant cette clé Idempotency-Key est encore en cours de traitement. Réessayez la même clé sous peu plutôt que d’en utiliser une nouvelle.
409	EMAIL_TEMPLATE_ALIAS_TAKEN	Un autre modèle de ce compte utilise déjà cet alias.
409	EMAIL_TEMPLATE_IN_USE	Un courriel programmé utilise ce modèle. Annulez-le, ou attendez qu’il soit envoyé, puis supprimez le modèle.
409	RECEIVING_REQUIRES_VERIFIED_DOMAIN	Le domaine doit être vérifié pour l’envoi avant que la réception puisse être activée.
410	ATTACHMENT_EXPIRED	La pièce jointe ou le message brut a dépassé sa fenêtre de conservation de 40 jours.
413	EMAIL_ATTACHMENT_TOO_LARGE	Les pièces jointes dépassent 25 Mo.
422	EMAIL_INVALID_ADDRESS	Une adresse n’est pas une adresse courriel valide.
422	EMAIL_DOMAIN_NOT_VERIFIED	Le domaine de l’expéditeur n’est pas un domaine d’envoi vérifié de ce compte.
422	EMAIL_DOMAIN_INVALID	Nom de domaine invalide.
422	EMAIL_DOMAIN_LIMIT_REACHED	Ce compte a atteint sa limite de domaines d’envoi (5 par défaut ; les domaines en échec ne comptent pas). Répondu à l’ajout d’un domaine, ou à la vérification d’un domaine en échec qui reprendrait une place. Retirez-en un ou demandez au soutien de l’augmenter.
422	EMAIL_TEST_ADDRESS_LIVE_KEY	Une clé réelle ne peut pas envoyer à une adresse sur test.honkio.ca ; ces adresses sont réservées aux clés de test.
422	EMAIL_HEADER_INVALID	L’adresse d’expéditeur ou un en-tête est mal formé, ou est un en-tête que honkio définit lui-même.
422	EMAIL_ATTACHMENT_FETCH_FAILED	Une pièce jointe fournie par path n’a pas pu être récupérée. details.reason indique pourquoi : blocked_address, http_status, timeout, too_large ou network.
422	EMAIL_ATTACHMENT_TYPE_BLOCKED	La pièce jointe est un exécutable ou un script (.exe, .js, .bat, .jar et similaires), un type que les serveurs de courriel destinataires refusent. details.filename l’identifie. Rien n’est facturé.
422	EMAIL_RENDER_FAILED	Le contenu n’a pas pu être généré.
422	EMAIL_BATCH_TOO_LARGE	Trop de destinataires dans un seul appel.
422	EMAIL_COMMERCIAL_MULTI_RECIPIENT	Un courriel commercial va à un seul destinataire. Utilisez un envoi groupé pour en joindre plusieurs.
422	EMAIL_NOT_SCHEDULED	Seul un courriel programmé peut être déplacé ou annulé.
422	EMAIL_TEMPLATE_NOT_PUBLISHED	Le modèle n’a pas encore de version publiée. Publiez-le avant de l’utiliser pour un envoi.
422	EMAIL_TEMPLATE_VARIABLE_MISSING	Une variable du modèle n’a ni valeur ni valeur de repli. details.keys énumère celles qui manquent.
422	EMAIL_TEMPLATE_UNDECLARED_VARIABLE	Le corps du modèle utilise une variable qu’il ne déclare pas. Ajoutez-la à variables ; details.keys les énumère.
422	EMAIL_TEMPLATE_LIMIT_REACHED	Ce compte a atteint la limite de 200 modèles de courriel. Supprimez-en un pour en créer un autre.
422	SIMULATE_RECIPIENT_NOT_OWNED	Chaque destinataire simulé doit être votre adresse de test ou un domaine que ce compte possède en mode test.
422	INBOUND_ADDRESS_DISABLED	Votre adresse entrante gérée est désactivée. Réactivez-la avant d’y envoyer.
451	EMAIL_SUPPRESSED	Le destinataire figure sur votre liste de suppression.
451	EMAIL_NO_CONSENT	Le courriel commercial exige un consentement LCAP enregistré pour le destinataire.
451	EMAIL_OPT_OUT_BLOCKED	Le destinataire s’est désabonné de cet expéditeur.
503	EMAIL_ATTACHMENTS_UNCONFIGURED	Le stockage des pièces jointes n’est pas configuré, donc les courriels avec pièces jointes ne peuvent pas être envoyés pour le moment.

Codes d’échec de livraison

Ces codes ne sont jamais une réponse HTTP : l’appel a déjà répondu 201 avant que SES tente l’envoi. Si la livraison échoue quand même, l’un d’eux apparaît comme failure_code sur le webhook email.failed ou email.rejected, et les frais sont remboursés.

Code	Signification
SES_THROTTLING	SES a limité le débit d’envoi ; le courriel a échoué et a été remboursé ; renvoyez-le.
SES_MESSAGE_REJECTED	SES a rejeté le message d’emblée, par exemple un contenu mal formé ; le courriel a échoué et a été remboursé ; corrigez le contenu et renvoyez-le.
SES_DOMAIN_NOT_VERIFIED	SES n’avait pas terminé de vérifier le domaine d’expéditeur, même si la vérification de honkio avait réussi ; le courriel a échoué et a été remboursé ; attendez la fin de la vérification, puis renvoyez-le.
SES_ERROR	Une erreur SES qui ne correspond à aucun autre code ; le courriel a échoué et a été remboursé ; renvoyez-le.
EMAIL_ATTACHMENTS_UNAVAILABLE	Les octets de la pièce jointe stockée n’ont pas pu être lus au moment de l’envoi ; le courriel a échoué et a été remboursé ; renvoyez-le.