Erreurs

Chaque refus a la même forme, application/problem+json, sur toutes les routes :

{
  "type": "/errors/UNAUTHENTICATED",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required to access this resource.",
  "code": "UNAUTHENTICATED"
}

Vous la voyez en appelant l’API sans clé :

curl --silent --show-error --include https://api.facteur.eu/inboxes

Brancher sur `code`

code est le membre que votre client teste. detail est une phrase en anglais pour la personne qui lit un pipeline rouge, et sa formulation peut changer. Ne l’analysez pas et ne faites pas d’assertion dessus. Pour montrer un refus dans une autre langue, traduisez le code.

Un refus qui a besoin d’une valeur pour être utile la porte dans un membre à part, à côté de detail. Le 403 d’une permission manquante a permission, et l’opération qui peut le renvoyer le documente dans la référence. Un échec de validation (VALIDATION_FAILED) liste chaque champ dans violations, avec son propertyPath, son message et son propre code.

Authentification

Statut	Code	Ce que vous faites
401	`UNAUTHENTICATED`	Ajoutez l’en-tête `Authorization`.
401	`API_KEY_UNKNOWN`	Vérifiez ce que votre pipeline envoie. Cette clé n’a jamais existé.
401	`API_KEY_REVOKED`	Créez une nouvelle clé. Une personne a révoqué celle-ci.
401	`API_KEY_EXPIRED`	Créez une nouvelle clé, et faites-le avant la date la prochaine fois.
403	`API_KEY_PERMISSION_MISSING`	Donnez à la clé la permission nommée dans `permission`, ou appelez une opération qu’elle atteint déjà.
403	`API_KEY_CANNOT_DELETE_WORKSPACE`	Supprimez l’espace de travail depuis l’application Facteur. Aucune clé ne le fait.

Authentification explique les permissions et les trois raisons d’un 401.

Introuvable

Code	Ce que vous faites
`INBOX_NOT_FOUND`	Vérifiez l’identifiant, puis vérifiez que la clé atteint l’espace de travail de l’inbox.
`MESSAGE_NOT_FOUND`	Pareil, pour un message.
`WORKSPACE_NOT_FOUND`	Pareil, pour l’adresse d’un espace de travail.
`MEMBER_NOT_FOUND`	La personne n’est pas membre de cet espace de travail.
`EXTRACTOR_NOT_FOUND`	Vérifiez l’identifiant de l’extracteur et l’inbox à laquelle il appartient.
`ATTACHMENT_NOT_FOUND`	Vérifiez l’identifiant de la pièce jointe.
`ATTACHMENT_NOT_STORED`	Facteur n’a jamais gardé le contenu de cette pièce jointe. Son champ `reason`, dans le message, dit pourquoi.
`SMS_REQUEST_NOT_FOUND`	Cette inbox n’a jamais demandé de numéro SMS. Demandez-en un par un `POST` sur le même chemin.

Tous répondent 404. Une ressource d’une autre organisation, ou d’un espace de travail que la clé n’atteint pas, reçoit le même 404 qu’une ressource qui n’existe pas.

Une recherche sur une inbox que la clé n’atteint pas répond aussi 404, jamais une liste vide. Distinguez les deux dans votre test : une liste vide veut dire que le courrier n’est pas arrivé, un 404 que vous cherchez au mauvais endroit.

curl --silent --show-error --include \
  -H "Authorization: Bearer $FACTEUR_API_KEY" \
  https://api.facteur.eu/inboxes/zzzzzzzz/messages

Recherche

Statut	Code	Ce que vous faites
400	`CRITERIA_EMPTY`	Nommez un ensemble : une inbox, un destinataire, un sujet, un code ou une date.
400	`CRITERIA_UNKNOWN`	Corrigez le champ que `detail` nomme. Ce n’est pas un critère de la recherche.
400	`CRITERIA_INVALID`	Corrigez la valeur du champ que `detail` nomme : un texte plus long que sa longueur maximale (Limites les liste), un `limit` qui n’est pas un nombre entier, une date qui n’en est pas une, un booléen qui n’est ni `true` ni `false`.
400	`INVALID_CURSOR`	Renvoyez le `nextCursor` de la page précédente, tel quel, ou omettez `cursor`.

Les deux formes de la recherche, GET/messages et POST/messages/search, répondent les mêmes codes. Un POST dont le corps n’est pas du JSON répond 400 BAD_REQUEST.

CRITERIA_UNKNOWN est celui qui surprend. Si subjet était ignoré à la place de subject, la recherche correspondrait à tous les messages de l’inbox, votre test ferait son assertion sur le premier, et il passerait jusqu’au jour où un deuxième message arrive.

curl --silent --show-error --include --get \
  -H "Authorization: Bearer $FACTEUR_API_KEY" \
  --data-urlencode "inbox=j3k9x2mq" \
  --data-urlencode "subjet=code" \
  https://api.facteur.eu/messages

L’autre refus d’une recherche est une valeur trop longue. Un objet fait 255 caractères au plus, et un objet plus long est refusé au lieu d’être coupé, parce qu’un texte coupé correspondrait à d’autres messages :

curl --silent --show-error --include --get \
  -H "Authorization: Bearer $FACTEUR_API_KEY" \
  --data-urlencode "subject=$(printf 'a%.0s' {1..300})" \
  https://api.facteur.eu/messages

Débit et disponibilité

Statut	Code	Ce que vous faites
429	`RATE_LIMITED`	Attendez le nombre de secondes de `Retry-After`, puis envoyez moins de requêtes. Une clé en fait 600 par minute.
429	`TOO_MANY_WAITS`	Attendez chaque recherche avant d’envoyer la suivante, baissez le nombre de workers, ou raccourcissez `wait`.
503	`API_DRAINING`	Renvoyez la même requête après le délai de `Retry-After`. L’instance qui l’a reçue était en train de s’arrêter.
503	`ATTACHMENT_STORE_UNAVAILABLE`	Réessayez le téléchargement un peu plus tard.

Les deux 429 comptent des choses différentes : le code vous dit quoi changer. Limites donne les chiffres.

Plafonds de l’offre

Ces refus répondent 402. Ils viennent de l’offre de l’organisation, pas de la clé :

Code	Ce que vous faites
`INBOX_LIMIT_REACHED`	Supprimez une inbox, ou changez d’offre.
`WORKSPACE_LIMIT_REACHED`	Supprimez un espace de travail, ou changez d’offre.
`INBOX_QUOTAS_UNAVAILABLE`	L’offre n’inclut pas les plafonds par inbox. Retirer un plafond marche sur toutes les offres.
`WORKSPACE_QUOTAS_UNAVAILABLE`	L’offre n’inclut pas les plafonds par espace de travail. Retirer un plafond marche sur toutes les offres.
`SMS_NUMBER_LIMIT`	L’offre ne tient plus de numéro SMS. `limit` et `occupied` disent combien elle en tient et combien sont pris, `requiredPlan` nomme l’offre qui en tient un de plus. Retirez une demande, ou changez d’offre.

Numéros SMS

Une demande de numéro SMS est lue par une personne de l’équipe Facteur, qui donne le numéro. Voici les refus de la demande elle-même :

Statut	Code	Ce que vous faites
400	`SMS_COUNTRY_NOT_OPEN`	Demandez un pays de la liste `countries`, ou omettez `country` pour le Royaume-Uni.
400	`SMS_NOTE_TOO_LONG`	Raccourcissez `note` à `max` caractères.
409	`SMS_REQUEST_ALREADY_OPEN`	L’inbox a déjà une demande en attente. Lisez-la par un `GET`, ou retirez-la avant de redemander.
409	`SMS_REQUEST_NOT_WITHDRAWABLE`	La demande a déjà été refusée ou retirée : il n’y a plus rien à retirer.

Un message refusé à la réception

Il arrive qu’un message arrive alors qu’une limite est atteinte. Facteur le garde avec le statut quota_exceeded et n’en lit rien. Il porte la raison dans errorCode, et aucun des champs lus dans le corps (subject, otp, links, extract). Lisez status avant d’en lire un.

`errorCode`	Ce que vous faites
`PLAN_QUOTA_EXCEEDED`	La capacité de l’offre est dépensée pour cette période.
`INBOX_QUOTA_EXCEEDED`	Relevez ou retirez le plafond que vous avez posé sur cette inbox.
`WORKSPACE_QUOTA_EXCEEDED`	Relevez ou retirez le plafond que vous avez posé sur cet espace de travail.
`OVERAGE_CAP_REACHED`	Relevez le plafond de dépense que vous avez choisi, ou achetez de la capacité.
`DAILY_SPIKE_CAP`	Attendez le lendemain.
`SUBSCRIPTION_SUSPENDED`	Réglez la facture en attente.

Ce sont des décisions d’une personne, dans l’application Facteur. Une clé d’API ne peut en changer aucune.

Les routes de cette API sont listées dans la référence, chacune avec les refus qu’elle peut renvoyer. Par exemple, GET/messages peut renvoyer les codes du tableau de recherche ci-dessus.