# Erreurs > Codes de statut, codes d'erreur, erreurs de champ, limites de débit, identifiants de requête, et comment réessayer sans risque. Source : https://abuna.app/docs/errors?hl=fr Cette page liste toutes les erreurs que renvoie l'API, pour que votre code traite chacune d'elles. Une requête qui échoue renvoie un statut `4xx` ou `5xx` et un corps JSON. Le corps contient un `code` qui reste le même et une phrase `error` destinée aux développeurs. Basez votre code sur le statut et le `code`. N'analysez pas `error`, car sa formulation peut changer. **Corps d'erreur** ```json { "code": "unauthenticated", "error": "missing or invalid API key" } ``` ## Identifiants de requête Chaque réponse, échouée ou non, a un en-tête `X-Request-Id`, comme `req_01J9ZQB21C3D4E5F6G7H8J9K0M`. Journalisez-le avec votre propre trace de la requête. Quand vous contactez le support au sujet d'une requête, citez son `X-Request-Id`. ## Erreurs de champ Quand une requête échoue à cause de son entrée, le corps contient aussi un tableau `errors`, avec un élément par champ. Une validation échouée renvoie `422` avec le code `invalid` et liste chaque champ qui a échoué. **Erreurs de champ (422)** ```json { "code": "invalid", "error": "email is required; phone_number is required", "errors": [ { "field": "email", "code": "required", "error": "email is required" }, { "field": "phone_number", "code": "required", "error": "phone_number is required" } ] } ``` Le `code` de chaque élément est l'un des suivants : - `required` : le champ est manquant ou vide. - `invalid` : la valeur n'est pas autorisée, comme un montant de `0` ou un statut inconnu. - `currency_unsupported` : la devise n'est ni `XAF`, ni `XOF`, ni `USD`. - `phone_invalid` : le numéro de téléphone n'a pas d'indicatif pays, ou n'a pas le bon nombre de chiffres pour son pays. - `phone_country_unsupported` : votre prestataire de paiement ne peut pas débiter les numéros de ce pays. La page d'abonnement et l'espace client les refusent. - `phone_required` : le client n'a pas encore de numéro de téléphone, donc aucun numéro à débiter. Voir [`phone_required`](https://abuna.app/docs/errors.md?hl=fr#error-codes) plus bas. - `unchanged` : la valeur est celle déjà définie, comme un nouveau montant de prix égal au montant actuel. - `too_soon` : la date est trop proche, comme un changement de prix à moins de 14 jours. - `too_long` : une `note` de paiement dépasse 500 caractères. - `unknown_field` : une mise à jour a envoyé un champ que l'endpoint n'accepte pas. - `invalid_json` : la valeur n'a pas le bon type, ou l'endpoint n'accepte pas ce champ. La réponse est un `400`. - `price_not_eligible` : l'abonnement ne peut pas passer au `price_id` que vous avez envoyé. - `not_found` : l'ID du champ n'existe pas dans l'application, comme un `price_id` ou un `invoice_id` quand vous créez une session. - `url_invalid` : l'URL n'est pas une URL absolue avec un hôte, ou utilise `http` là où seul `https` est autorisé. Le slug d'un produit doit être unique dans son application. Un slug que vous envoyez et qu'un autre produit possède renvoie `409` avec le code `slug_taken`, et son élément `errors` nomme le champ `slug`. Un slug qu'Abuna construit à partir du nom n'entre jamais en conflit. ## Codes d'erreur Voici les codes qu'une requête avec une clé secrète peut recevoir. Chaque code indique le statut HTTP qui l'accompagne. **Codes d'erreur** - `invalid_json` (400): Le corps est vide, n'est pas un JSON valide, contient une valeur du mauvais type, ou un champ que l'endpoint n'accepte pas. Pour un mauvais type ou un champ inconnu, errors nomme le champ. - `live_app_required` (400): Vous avez demandé à [copier les produits de Test vers Production](https://abuna.app/docs/api/products.md?hl=fr#copy-from-test) avec un ID d'application Test. Utilisez l'ID de l'application en production. - `test_app_required` (400): Vous avez demandé à [copier les produits de Production vers Test](https://abuna.app/docs/api/products.md?hl=fr#copy-from-live) avec un ID d'application en production. Utilisez l'ID de l'application Test. - `invalid` (422): Un ou plusieurs champs ont échoué à la validation. Voir `errors` pour chaque champ. Un en-tête `Idempotency-Key` de plus de 255 caractères reçoit ce code avec `400`. - `payment_declined` (402): Le paiement a échoué. Le prestataire peut aussi donner une raison plus précise, listée plus bas. - `insufficient_funds` (402): Le solde du client est trop bas. - `payment_not_approved` (402): Le client a refusé la demande sur son téléphone ou l'a laissée expirer. - `wallet_not_found` (402): Le numéro n'a pas de portefeuille sur le réseau débité, ou n'est pas un numéro valide. - `wallet_limit_reached` (402): Le portefeuille du client a atteint une limite de transaction ou de solde. - `wallet_busy` (402): Un autre paiement attend déjà l'approbation du client. - `network_unavailable` (402): Le réseau ne peut pas prendre ce paiement maintenant, ou ne peut pas le prendre du tout avec votre compte de paiement. - `amount_too_low` (402): Le montant est inférieur au plus petit paiement que votre prestataire accepte, donc réessayer n'y changera rien. - `unauthenticated` (401): La requête n'a pas de clé, ou la clé est incorrecte ou révoquée. Vérifiez l'en-tête Authorization. - `forbidden` (403): Une clé secrète a appelé un endpoint qui exige une connexion au tableau de bord, ou une connexion au tableau de bord ou une clé publiable a appelé un endpoint qui exige une clé secrète, comme les sessions. - `email_unverified` (403): L'application est en mode Production et le propriétaire d'équipe n'a pas vérifié son e-mail. - `plan_limit` (403): La requête dépasserait une limite de votre forfait, comme son nombre d'abonnés en production. - `plan_read_only` (403): Votre forfait a rendu cette application en production en lecture seule. Les lectures fonctionnent toujours, tout comme le débit d'une facture. - `not_found` (404): L'objet nommé dans le chemin n'existe pas dans l'application, ou, quand vous créez un prix ou un abonnement, un ID que vous avez envoyé n'y existe pas ; errors nomme alors ce champ. Un ID d'application qui n'existe pas, ou auquel votre clé n'appartient pas, reçoit aussi ce code. - `slug_taken` (409): Un autre produit de l'application a déjà le slug que vous avez envoyé. Envoyez un slug différent. - `code_taken` (409): Un autre [code promotionnel](https://abuna.app/docs/api/promotion-codes.md?hl=fr) de l'application a déjà ce code. Les codes ignorent la casse, donc `BLACKFRIDAY` et `blackfriday` sont identiques. Envoyez un autre code. - `test_app_missing` (409): L'application n'a pas de mode Test depuis lequel copier les produits. - `already_paid` (409): La facture est déjà payée. - `invoice_not_open` (409): La facture est annulée (void), par exemple parce que l'abonnement a été résilié. Vous ne pouvez pas créer de session pour la payer. - `subscription_canceled` (409): L'abonnement a pris fin, donc une résiliation programmée ne peut pas être retirée et vous ne pouvez pas demander de résiliation. Créez plutôt un nouvel abonnement. - `subscription_not_active` (409): Vous ne pouvez demander une résiliation que pour un abonnement actif ou impayé (active ou past_due). Un abonnement pending, dont la première période n'est pas encore payée, reçoit ce code. - `cancel_already_scheduled` (409): L'abonnement est déjà programmé pour être résilié, vous ne pouvez donc pas demander de résiliation. - `payment_in_progress` (409): Un paiement pour cette facture attend déjà une approbation. Un changement de formule ou une résiliation qui annulerait une période impayée, ou remplacerait une montée de formule en attente de paiement, reçoit aussi ce code tant que ce paiement est en cours. - `plan_change_unavailable` (409): L'abonnement n'est ni actif ni impayé (active ou past_due), sa formule ne peut donc pas changer. Un abonnement dont la première période n'est pas encore payée ne peut pas changer de formule. - `renewal_paid_early` (409): Le client a déjà payé la période suivante avant qu'elle commence, donc une montée de formule attend le début de cette période. Rien n'a été débité. - `session_not_open` (409): La session est déjà terminée ou expirée, elle ne peut donc pas être expirée. - `idempotency_in_progress` (409): Une requête avec la même Idempotency-Key est toujours en cours. Réessayez dans un instant. - `no_pending_change` (409): Le prix n'a aucun changement programmé à retirer. - `change_in_effect` (409): Le changement en attente du prix a atteint son effective_at et prend effet, il ne peut donc pas être remplacé ni retiré. Cela dure de effective_at jusqu'à l'événement price_change.applied, généralement moins d'une minute. Ensuite, vous pouvez programmer un nouveau changement. - `conflict` (409): La requête entre en conflit avec l'état actuel de l'objet. - `price_archived` (410): Le prix, ou le produit auquel il appartient, est archivé, aucun nouvel abonnement ne peut l'utiliser. - `already_subscribed` (409): Sur la page d'abonnement, le client a déjà un abonnement actif ou impayé (active ou past_due) à ce prix, reconnu par son e-mail. Le numéro de téléphone ne compte pas : le même numéro avec un autre e-mail passe. Rien n'a été créé ni débité. La page d'abonnement lui propose de recevoir par e-mail les liens de son abonnement. Un abonnement encore en attente de son premier paiement ne provoque pas cette erreur : la page ramène le client à ce paiement. Un abonnement à un autre prix, ou un abonnement résilié ou terminé, non plus. - `session_expired` (410): La session a expiré avant que le client ait soumis ses informations. La page d'abonnement reçoit ce code, pas votre serveur. Créez une nouvelle session. - `price_not_eligible` (422): L'abonnement ne peut pas passer à ce prix : c'est le prix actuel, il est archivé, il est pour un autre produit, dans une autre devise, ou n'est pas dans l'application. La phrase error de son élément price_id précise lequel de ces cas s'applique ; lisez-la, mais n'en faites pas dépendre votre code. - `coupon_invalid` (422): Une réduction envoyée dans `discounts` ne peut pas être utilisée sur cette page d'abonnement ou cet abonnement : le coupon ou le code est inconnu, désactivé, expiré, épuisé, réservé à d'autres produits, dans une autre devise, ou ferait passer le montant sous le minimum facturable. L'élément `errors` nomme `discounts`. - `promotion_code_invalid` (422): Le code du client est inconnu, désactivé, expiré, épuisé, ou son coupon n'est plus valide. L'élément `errors` nomme `code`. Le client le voit à côté du champ : « Ce code ne fonctionne pas. Vérifiez son orthographe, ou demandez un code valide au vendeur. » - `promotion_code_not_applicable` (422): Le coupon du code est réservé à d'autres produits, ou dans une autre devise. L'élément `errors` nomme `code`. - `promotion_code_amount_too_low` (422): Le coupon du code ferait passer le montant sous le minimum facturable : 100 XAF ou XOF, ou 50 centimes USD. L'élément `errors` nomme `code`. - `promotion_code_first_time_only` (422): Le code est réservé aux clients qui n'ont jamais payé cette application, et ce client a déjà payé. L'élément `errors` nomme `code`. - `not_accepting_payments` (422): L'application en production ne peut pas encore encaisser de paiements : le propriétaire d'équipe n'a pas vérifié son e-mail, aucun prestataire de paiement n'est connecté, ou l'application n'a pas d'e-mail ni d'URL de support. L'objet `payments` de [l'application](https://abuna.app/docs/api/apps.md?hl=fr#object) indique ce qui manque. Une montée de formule avec un montant à payer reçoit aussi ce code. - `payment_unavailable` (422): La méthode de paiement n'est pas proposée. - `phone_required` (422): Vous avez demandé à [débiter une facture](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#charge), mais le client n'a pas encore de numéro de téléphone. Un client venu par la page d'abonnement n'en a pas avant son premier paiement. L'élément `errors` nomme `phone_number`. Ajoutez un numéro avec [Mettre à jour un client](https://abuna.app/docs/api/customers.md?hl=fr#update), ou envoyez-lui une [session de paiement](https://abuna.app/docs/api/sessions.md?hl=fr#create-payment), qui le demande. La page de paiement reçoit aussi ce code quand elle n'envoie aucun numéro pour un tel client. - `idempotency_key_reused` (422): L'Idempotency-Key a déjà été utilisée avec une requête différente au cours des dernières 24 heures. Utilisez une nouvelle clé pour une nouvelle requête. - `webhook_url_missing` (422): Vous avez demandé d'envoyer ou de renvoyer un webhook, mais l'application n'a pas d'URL de webhook. - `rate_limited` (429): Trop de requêtes. Voir [Limites de débit](https://abuna.app/docs/errors.md?hl=fr#rate-limits). - `internal` (500): Quelque chose s'est mal passé du côté d'Abuna. Réessayez plus tard. - `payment_paused` (503): Vous avez demandé à [débiter une facture](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#charge), mais aucun nouveau paiement n'a été lancé. Un paiement précédent sur la facture est peut-être encore en cours. Réessayez dans une minute environ. - `exchange_rate_unavailable` (503): La facture est en USD et aucun taux de change récent n'est disponible, donc elle ne peut pas être payée pour l'instant. Rien n'a été débité. Réessayez plus tard. Les taux sont normalement disponibles chaque jour. Sur la page de paiement, le client est invité à réessayer plus tard. Voir [Paiement en FCFA](https://abuna.app/docs/amounts-currencies-and-timestamps.md?hl=fr#paying-in-fcfa). ## Limites de débit - Chaque adresse IP peut faire 600 requêtes par minute. - Chaque application peut envoyer 10 webhooks de test par minute. Au-delà d'une limite, l'API renvoie `429` avec le code `rate_limited` et un en-tête `Retry-After`. Attendez ce nombre de secondes, puis réessayez. **Limite de débit atteinte (429)** ```json { "code": "rate_limited", "error": "too many requests" } ``` ## Requêtes idempotentes Chaque `POST` et `DELETE` accepte un en-tête `Idempotency-Key`, pour que vous puissiez réessayer une requête après une erreur réseau ou un `5xx` sans refaire le travail. Envoyez une nouvelle valeur aléatoire, jusqu'à 255 caractères, pour chaque nouvelle requête, et la même valeur à chaque nouvelle tentative de celle-ci. Sans l'en-tête, chaque requête s'exécute. **POST /v1/apps/{appID}/sessions avec Idempotency-Key** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43" \ -d '{ "type": "checkout", "price_id": "Zt6YbN3q", "metadata": {"user_id": "42"} }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43", }, body: JSON.stringify({ type: "checkout", price_id: "Zt6YbN3q", metadata: { user_id: "42" }, }), }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43"}, json={ "type": "checkout", "price_id": "Zt6YbN3q", "metadata": {"user_id": "42"}, }, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json", "Idempotency-Key: 6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43"], CURLOPT_POSTFIELDS => json_encode([ "type" => "checkout", "price_id" => "Zt6YbN3q", "metadata" => ["user_id" => "42"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "type": "checkout", "price_id": "Zt6YbN3q", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` Abuna conserve une clé pendant 24 heures, par application. Quand une requête réutilise une clé : - La même requête, vers le même chemin avec le même corps, reçoit à nouveau la première réponse, avec son statut et son corps, plus l'en-tête `Idempotent-Replayed: true`. - Une requête différente renvoie `422` avec le code `idempotency_key_reused`. - Tant que la première requête est en cours, elle renvoie `409` avec le code `idempotency_in_progress`. Une requête qui débite un client peut durer jusqu'à une minute : réessayez à quelques secondes d'intervalle pendant ce temps. - Si la première requête a reçu un `5xx`, la clé n'est pas conservée, donc la nouvelle tentative s'exécute à nouveau. - Toute autre réponse est conservée, erreurs comprises. Un `4xx`, comme un paiement refusé, revient identique pendant 24 heures. Pour réessayer après, envoyez une nouvelle clé. Une clé de plus de 255 caractères renvoie `400` avec le code `invalid`.