---
title: "Erreurs"
description: "Le format des erreurs de l'API Matchai, chaque code avec son statut HTTP et la marche à suivre, les requêtes à réessayer et les identifiants de requête."
last_updated: "2026-10-21"
lang: "fr-CA"
status: "coming-soon"
canonical: "https://matchai.co/docs/fr/developers/errors"
---
# Erreurs
> Le format des erreurs de l'API Matchai, chaque code avec son statut HTTP et la marche à suivre, les requêtes à réessayer et les identifiants de requête.
**Bientôt disponible. Cette fonctionnalité est documentée avant son lancement pour que vous puissiez planifier votre intégration; elle n’est pas encore offerte.**
Source: https://matchai.co/docs/fr/developers/errors
Chaque erreur de l'API Matchai a la même forme JSON. Basez votre logique sur le `code` stable, et montrez le `message` à la personne qui utilise votre application : il dit ce qui s'est passé et quoi faire ensuite.
## Le format des erreurs [#the-error-format]
```json title="Response (400)"
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "price.amount must be greater than 0.",
"param": "price.amount",
"doc_url": "https://matchai.co/docs/developers/errors#parameter_invalid",
"request_id": "req_7Hq2LmZ9xV4c"
}
}
```
Trois habitudes rendent les erreurs faciles à gérer :
- **Basez-vous sur `code`, pas sur `message`.** Les codes sont stables. Les messages sont écrits pour des personnes, suivent la langue du compte et peuvent être reformulés.
- **Traitez les valeurs inconnues comme inconnues, pas comme un plantage.** De nouveaux codes et de nouveaux types peuvent être ajoutés sans nouvelle version. Si vous rencontrez un `code` que vous ne connaissez pas, rabattez-vous sur son `type` et son statut HTTP. Un `type` inconnu se traite comme `api_error`.
- **Journalisez l'identifiant de requête.** Consultez [Identifiants de requête](#request-ids).
## Codes d'état [#status-codes]
| Statut | Type | Signification | Réessayer? |
|---|---|---|---|
| `202` | Aucun | Ce n'est pas une erreur. Une [action finale](https://matchai.co/docs/fr/developers/authentication#final-actions) attend l'approbation du titulaire du compte. Rien ne s'est encore passé. | Non. Attendez `approval.resolved`. |
| `400` | `invalid_request_error` | La requête est mal formée ou un paramètre est invalide. | Non. Corrigez la requête. |
| `401` | `authentication_error` | La clé ou le jeton est absent, expiré, révoqué ou erroné. | Une fois, après avoir actualisé un jeton expiré. |
| `402` | `energy_error` | Pas assez d'Énergie Matchai, ou la connexion a atteint sa limite d'énergie. | Non, pas avant qu'il y ait de nouveau de l'énergie. |
| `403` | `permission_error` | L'identifiant de connexion est valide, mais ne permet pas cette action. | Non. |
| `404` | `not_found_error` | La ressource n'existe pas, ou ce compte ne peut pas la voir. | Non. |
| `409` | `conflict_error` | La requête entre en conflit avec l'état actuel. | Non. Modifiez la requête. |
| `422` | `unprocessable_error` | La requête est bien formée, mais enfreint une règle du produit. | Non. Modifiez la requête. |
| `429` | `rate_limit_error` | Trop de requêtes pour cette connexion. | Oui, après `Retry-After` secondes. |
| `500` | `api_error` | Un problème est survenu du côté de Matchai. | Oui, avec le même `Idempotency-Key`. |
## Identifiants de requête [#request-ids]
Chaque réponse, réussie ou non, porte un en-tête `Matchai-Request-Id`. Les erreurs le répètent dans `error.request_id`. Journalisez-le avec chaque appel qui échoue. Quand vous communiquez avec [l'assistance Matchai](https://matchai.co/support), incluez-le : il permet à Matchai de trouver exactement ce qui s'est passé lors de cette requête.
```http title="Response header"
Matchai-Request-Id: req_7Hq2LmZ9xV4c
```
## Réessayer sans risque [#retry-safely]
Réessayer est sans risque quand la même requête peut être répétée sans que l'action se fasse deux fois. C'est à cela que sert l'en-tête `Idempotency-Key`.
- Envoyez un `Idempotency-Key` avec chaque `POST`. Un UUID convient.
- Une nouvelle tentative avec la **même clé** dans les 24 heures renvoie la première réponse au lieu d'agir deux fois. Une nouvelle tentative d'une action finale sous **Me demander** renvoie la même approbation en attente.
- Réutiliser une clé avec un **corps différent** renvoie `409 idempotency_key_reused`. Créez une nouvelle clé pour une nouvelle requête.
Réessayez après une erreur réseau, un dépassement de délai, un `429` ou un `500`. Ne réessayez pas un `400`, un `403`, un `404`, un `409` ou un `422` sans rien changer : ils échoueront de la même façon. Un `402` continue d'échouer jusqu'à ce que le compte ait de nouveau de l'énergie ou que le titulaire du compte relève la limite de la connexion.
Attendez avant chaque nouvelle tentative : respectez `Retry-After` quand il est présent, et sinon attendez un peu plus longtemps chaque fois, avec un peu d'aléatoire pour que de nombreux clients ne réessaient pas tous en même temps.
```js title="retry.mjs"
import { randomUUID } from 'node:crypto';
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 1 s, 2 s, 4 s... plus up to a second of jitter.
const backoff = (attempt) => 2 ** (attempt - 1) * 1000 + Math.random() * 1000;
export async function postWithRetry(url, body, { attempts = 4 } = {}) {
const idempotencyKey = randomUUID(); // The same key on every attempt.
for (let attempt = 1; ; attempt += 1) {
let response;
try {
response = await fetch(url, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey,
},
body: JSON.stringify(body),
});
} catch (networkError) {
if (attempt >= attempts) throw networkError;
await sleep(backoff(attempt));
continue;
}
const retryable = response.status === 429 || response.status >= 500;
if (!retryable || attempt >= attempts) return response;
const retryAfter = Number(response.headers.get('Retry-After'));
await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
}
}
```
## Codes d'erreur [#error-codes]
Chaque code ci-dessous est la cible du `doc_url` qui l'accompagne.
### Requêtes invalides [#invalid-requests]
#### `parameter_invalid` [#parameter_invalid]
**`400` · `invalid_request_error`.** Un champ est absent, a le mauvais type ou est hors limites. `param` nomme le champ, avec des points pour les champs imbriqués, comme `price.amount`. Corrigez la requête : la renvoyer sans changement échoue de nouveau.
Les autres réponses `400`, comme un corps qui n'est pas du JSON valide, portent le même `type`. Traitez tout `400` comme « cette requête est erronée ».
### Authentification [#authentication]
#### `token_expired` [#token_expired]
**`401` · `authentication_error`.** Le jeton d'accès est expiré. Avec [Se connecter avec Matchai](https://matchai.co/docs/fr/developers/authentication/connect-with-matchai), échangez votre jeton d'actualisation contre un nouveau jeton d'accès, puis répétez la requête une fois. Si l'actualisation échoue, la connexion a pris fin et le professionnel doit reconnecter son compte.
Un `401` peut aussi vouloir dire que la clé ou le jeton est absent, mal saisi ou révoqué, ou que la connexion a pris fin. Ces cas portent le même `type`. Demandez une nouvelle [clé d'API](https://matchai.co/docs/fr/developers/authentication/api-keys), ou faites repasser le professionnel par le flux de connexion.
### Énergie [#energy]
L'Énergie Matchai n'est jamais un nombre dans l'API. Ces erreurs indiquent seulement qu'il n'y en a pas assez.
#### `insufficient_energy` [#insufficient_energy]
**`402` · `energy_error`.** Le compte n'a pas assez d'Énergie Matchai pour cette action. Rien n'a été fait et rien n'a été dépensé. Le titulaire du compte peut en obtenir davantage dans le Matchai Store, et `GET /v1/me` indique l'état de son énergie (`full`, `comfortable`, `low` ou `empty`). Montrez le `message` à la personne, et réessayez une fois qu'elle a rechargé.
#### `energy_limit_reached` [#energy_limit_reached]
**`402` · `energy_error`.** Cette connexion a utilisé toute la limite d'énergie que le titulaire du compte a fixée pour elle. Rien n'a été fait et rien n'a été dépensé. `GET /v1/me/connection` indique `energy_limit_reached: true`. C'est le titulaire du compte qui décide s'il relève la limite; votre application ne devrait pas réessayer en boucle.
### Permissions [#permissions]
#### `scope_missing` [#scope_missing]
**`403` · `permission_error`.** La clé ou le jeton est valide, mais il lui manque la [portée](https://matchai.co/docs/fr/developers/authentication#scopes) dont cette action a besoin. Le `message` la nomme. Créez une nouvelle [clé d'API](https://matchai.co/docs/fr/developers/authentication/api-keys) qui inclut la portée, ou faites repasser le professionnel par le [flux de connexion](https://matchai.co/docs/fr/developers/authentication/connect-with-matchai) avec une liste de portées plus longue.
#### `not_allowed` [#not_allowed]
**`403` · `permission_error`.** Le rôle du compte ne permet pas cette action. La connexion agit avec les permissions propres au titulaire du compte, sans plus : ce qu'il ne peut pas faire dans Matchai, comme modifier le travail d'une équipe en tant que membre sans droit de modification, il ne peut pas le faire non plus par votre application. Avisez la personne, et ne réessayez pas.
### Introuvable [#not-found]
#### `resource_not_found` [#resource_not_found]
**`404` · `not_found_error`.** L'élément n'existe pas, ou ce compte ne peut pas le voir. Matchai donne la même réponse dans les deux cas, pour qu'une réponse ne confirme jamais que quelque chose existe dans le compte de quelqu'un d'autre. Vérifiez l'identifiant, et assurez-vous d'utiliser la clé ou le jeton du compte voulu.
### Conflits [#conflicts]
#### `contact_exists` [#contact_exists]
**`409` · `conflict_error`.** L'adresse courriel ou le numéro de téléphone que vous avez envoyé appartient déjà à l'un des contacts du compte, alors rien n'a été ajouté. L'identifiant du contact existant se trouve dans `error.param`. Mettez plutôt ce contact à jour, ou utilisez `POST /v1/enquiries`, qui fait le lien avec les contacts existants pour vous.
#### `subdomain_taken` [#subdomain_taken]
**`409` · `conflict_error`.** Le sous-domaine demandé n'est pas disponible. Les sous-domaines utilisent des lettres minuscules, des chiffres et des traits d'union. Choisissez-en un autre et réessayez.
#### `calendar_conflict` [#calendar_conflict]
**`409` · `conflict_error`.** L'heure chevauche un autre rendez-vous, et la réponse énumère les rendez-vous en conflit. Proposez une autre heure. N'envoyez `book_over_conflict: true` qu'une fois que le titulaire du compte a accepté le chevauchement.
#### `slot_unavailable` [#slot_unavailable]
**`409` · `conflict_error`.** La plage horaire demandée a été prise entre-temps, par exemple entre le moment où vous avez montré les plages libres à un visiteur et celui où vous avez enregistré sa demande de visite. Récupérez de nouveau les plages libres et proposez-en une autre.
#### `idempotency_key_reused` [#idempotency_key_reused]
**`409` · `conflict_error`.** Vous avez envoyé un `Idempotency-Key` que Matchai a déjà vu au cours des 24 dernières heures, avec un corps de requête différent. Utilisez une nouvelle clé pour une nouvelle requête. Ne réutilisez une clé que pour répéter exactement la même requête.
### Refusé par une règle du produit [#refused-by-a-product-rule]
#### `rooms_exceed_count` [#rooms_exceed_count]
**`422` · `unprocessable_error`.** Le nombre de chambres ou de salles de bain d'une inscription ne peut pas descendre sous le nombre de pièces de ce type décrites dans l'inscription. Retirez d'abord la pièce, puis réduisez le nombre. `param` nomme le champ, comme `property.bedrooms`.
#### `recipient_suppressed` [#recipient_suppressed]
**`422` · `unprocessable_error`.** Matchai n'enverra pas de courriel à cette adresse, parce que des messages précédents ont été retournés ou signalés comme indésirables. Avisez la personne, et joignez le contact autrement.
#### `contact_blocked` [#contact_blocked]
**`422` · `unprocessable_error`.** Ce contact est bloqué, alors Matchai refuse de lui écrire. Avisez la personne, et ne réessayez pas.
#### `content_not_allowed` [#content_not_allowed]
**`422` · `unprocessable_error`.** Le contenu envoyé enfreint les règles de contenu de Matchai. Le `message` indique quoi changer. Ne le renvoyez pas sans changement.
#### `handle_not_routable` [#handle_not_routable]
**`422` · `unprocessable_error`.** La publication de la Page Matchai a échoué parce que le nom d'utilisateur du compte ne peut pas encore servir d'adresse Web. Le titulaire du compte doit choisir un autre nom d'utilisateur dans Matchai.
### Limites de débit [#rate-limits]
#### `rate_limited` [#rate_limited]
**`429` · `rate_limit_error`.** Trop de requêtes pour cette connexion. La réponse porte `Retry-After`, le nombre de secondes à attendre. Consultez [Limites de débit](https://matchai.co/docs/fr/developers/rate-limits#in-the-matchai-api).
### Erreurs de Matchai [#matchai-errors]
#### `internal_error` [#internal_error]
**`500` · `api_error`.** Un problème est survenu du côté de Matchai. Vous pouvez réessayer sans risque avec le même `Idempotency-Key`, quelques fois, en espaçant de plus en plus les tentatives. Si l'erreur persiste, communiquez avec [l'assistance Matchai](https://matchai.co/support) en fournissant l'identifiant de requête.
Comment les requêtes sont limitées, et comment rester sous la limite.
Les portées, les actions finales et les limites d'énergie.
Les erreurs que chaque point de terminaison peut renvoyer.
## Sitemap
- [Toutes les pages de la documentation Matchai](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/fr/llms.txt)