ErreursBientôt disponible

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 erreursCopier le lien de cette section

{
  "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.

Codes d'étatCopier le lien de cette section

Identifiants de requêteCopier le lien de cette section

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, incluez-le : il permet à Matchai de trouver exactement ce qui s'est passé lors de cette requête.

Matchai-Request-Id: req_7Hq2LmZ9xV4c

Réessayer sans risqueCopier le lien de cette section

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.

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'erreurCopier le lien de cette section

Chaque code ci-dessous est la cible du doc_url qui l'accompagne.

Requêtes invalidesCopier le lien de cette section

parameter_invalidCopier le lien de cette section

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 ».

AuthentificationCopier le lien de cette section

token_expiredCopier le lien de cette section

401 · authentication_error. Le jeton d'accès est expiré. Avec Se connecter avec 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, ou faites repasser le professionnel par le flux de connexion.

ÉnergieCopier le lien de cette section

L'Énergie Matchai n'est jamais un nombre dans l'API. Ces erreurs indiquent seulement qu'il n'y en a pas assez.

insufficient_energyCopier le lien de cette section

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_reachedCopier le lien de cette section

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.

PermissionsCopier le lien de cette section

scope_missingCopier le lien de cette section

403 · permission_error. La clé ou le jeton est valide, mais il lui manque la portée dont cette action a besoin. Le message la nomme. Créez une nouvelle clé d'API qui inclut la portée, ou faites repasser le professionnel par le flux de connexion avec une liste de portées plus longue.

not_allowedCopier le lien de cette section

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.

IntrouvableCopier le lien de cette section

resource_not_foundCopier le lien de cette section

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.

ConflitsCopier le lien de cette section

contact_existsCopier le lien de cette section

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_takenCopier le lien de cette section

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_conflictCopier le lien de cette section

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_unavailableCopier le lien de cette section

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_reusedCopier le lien de cette section

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 produitCopier le lien de cette section

rooms_exceed_countCopier le lien de cette section

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_suppressedCopier le lien de cette section

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_blockedCopier le lien de cette section

422 · unprocessable_error. Ce contact est bloqué, alors Matchai refuse de lui écrire. Avisez la personne, et ne réessayez pas.

content_not_allowedCopier le lien de cette section

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_routableCopier le lien de cette section

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ébitCopier le lien de cette section

rate_limitedCopier le lien de cette section

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.

Erreurs de MatchaiCopier le lien de cette section

internal_errorCopier le lien de cette section

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 en fournissant l'identifiant de requête.