Erreurs de l'API

En quittant cette page, vous saurez lire n'importe quelle réponse d'erreur de l'API SealTrust. Vous reconnaîtrez le code renvoyé, vous déciderez s'il faut corriger votre requête ou la rejouer telle quelle, et vous retrouverez un appel précis dans nos journaux quand vous nous écrivez.

Cette page se lit en entier une fois, au moment où vous écrivez votre client. Elle sert ensuite de catalogue.

#Toutes les erreurs ont la même forme

Le corps d'une réponse d'erreur contient un seul champ : detail. Sa valeur prend trois formes, et vous devez savoir gérer les trois.

Une phrase. C'est la forme la plus courante. Le texte s'adresse à un lecteur humain.

{
  "detail": "Invalid API key"
}

Un objet qui porte un code. Certains refus liés à votre offre et certaines confirmations de suppression renvoient un objet. Le champ code est stable. Le champ message change au fil des versions.

{
  "detail": {
    "code": "QUOTA_EXCEEDED",
    "resource": "products",
    "current": 8,
    "additional": 5,
    "max": 10,
    "period": "monthly"
  }
}

Une liste. Quand la validation du corps ou des paramètres échoue, detail est une liste. Chaque entrée décrit une valeur refusée.

Selon la règle non respectée, une entrée peut porter des clefs supplémentaires. Lisez loc et type. Ne comparez jamais msg caractère par caractère.

#Les en-têtes qui accompagnent une réponse

#X-Request-Id, l'identifiant de chaque appel

Chaque réponse de l'API porte un en-tête X-Request-Id, une erreur 500 comprise. Si votre requête en envoie un, c'est le vôtre qui est repris, à condition qu'il fasse de 1 à 128 caractères pris parmi les lettres sans accent, les chiffres, le point, le tiret et le souligné. Sinon, ou si vous n'en envoyez pas, nous en fabriquons un.

Enregistrez cette valeur à côté de chaque appel qui échoue. Quand vous nous écrivez au sujet d'un refus, donnez-la : elle nous mène directement à l'appel concerné.

curl -sS -D - -o /dev/null \
  -X POST https://api.sealtrust.io/v1/partner/sellout \
  -H "Authorization: Bearer st_live_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: exemple-sas-2026-08-20-0001" \
  -d '{"identifier": "DEM000000000", "retailer_code": "BTQ-EXEMPLE-01"}'

#Les en-têtes de budget

Un appel authentifié par clef d'API porte les compteurs de débit dans sa réponse, y compris quand la route refuse ensuite. Un 400, un 403 dû à votre offre, à votre quota ou à une marque qui ne correspond pas, vous disent donc quel budget de débit il vous reste.

Trois familles de refus ne portent aucun compteur : les 401, les 403 de clef révoquée ou expirée, et les 403 de droit manquant sur la clef. Testez la présence de l'en-tête avant de lire sa valeur.

Un appel qui réussit ne vous dit pas combien de quota journalier il vous reste. Les trois en-têtes X-Quota-* n'existent que sur le refus 429 du quota. Pour suivre ce compteur avant de le heurter, ouvrez la liste des clefs d'API dans la console : elle affiche, pour chaque clef, la consommation du jour sur son quota.

#Le catalogue, code par code

#400, votre requête est mal formée

Le serveur a compris la requête et la refuse. Corrigez la requête. La rejouer telle quelle donnera le même résultat.

Les erreurs de lignes vous sont rendues toutes en même temps. Vous corrigez tout en un passage.

{
  "detail": {
    "error": "CSV invalide",
    "rows": [
      {
        "line": 2,
        "external_ref": "EX-0001",
        "error": "row: Value error, brand_code is required"
      }
    ]
  }
}

Le champ line est le numéro de ligne dans le fichier. La première ligne de données porte le numéro 2, puisque la ligne 1 est l'en-tête.

En JSON, la forme change : la position s'appelle index et commence à 1, et external_ref n'est pas repris.

{
  "detail": {
    "error": "JSON invalide",
    "rows": [
      {
        "index": 1,
        "error": "metadata_uri: Field required"
      }
    ]
  }
}

#401, l'API ne sait pas qui vous êtes

Votre requête n'a pas d'identité valide. Corrigez l'en-tête Authorization. Les deux premières lignes du tableau portent l'en-tête WWW-Authenticate: Bearer.

#403, l'API sait qui vous êtes et refuse

Votre identité est valide. Votre clef, votre offre ou votre périmètre ne couvrent pas cette opération. Rejouer la requête ne change rien.

L'objet QUOTA_EXCEEDED porte de quoi décider sans nous écrire :

{
  "detail": {
    "code": "QUOTA_EXCEEDED",
    "resource": "products",
    "current": 8,
    "additional": 5,
    "max": 10,
    "period": "monthly"
  }
}

#404, la ressource n'existe pas pour vous

Sur les points d'entrée publics et sur l'API à clef, un objet qui existe hors de votre périmètre répond 404, exactement comme un objet inexistant. Un point de vente d'une autre marque, un abonnement d'une autre marque, un produit d'une autre marque : la réponse est la même que pour un identifiant inventé.

Le portail partenaire suit la même règle. Un produit d'une marque qui ne vous a pas accrédité répond 404, quelle que soit la forme de l'identifiant. Sur le domaine propre d'une marque, le portail ne trouve que les produits de cette marque.

#409, l'état actuel interdit cette opération

La requête est correcte. Elle entre en conflit avec ce qui existe déjà.

Les deux messages du scellé NFC commencent par un code en majuscules suivi de deux points. Testez ce préfixe. La phrase qui suit peut être reformulée.

#413, l'envoi est trop gros

#422, l'API refuse une valeur que vous avez envoyée

C'est le code des paramètres et des corps de requête que le serveur sait lire et refuse. Le champ detail est alors une liste, sauf mention contraire dans le tableau.

#429, vous appelez trop souvent

Quatre compteurs différents rendent ce code. Les en-têtes vous disent lequel a refusé.

La console connectée lit votre session (GET /auth/state) et vos marques (GET /brands et les chemins en dessous) à chaque chargement de page. Avec une session valide, ces lectures se comptent par compte et non par adresse, à 600 par minute : plusieurs personnes d'un même bureau ne partagent pas ce compteur. Sans session valide, le plafond par adresse s'applique comme avant.

Un refus de plafond public porte Retry-After, en secondes. Attendez ce délai avant de rappeler.

Le refus du débit d'une clef d'API nomme le plafond qui a refusé et sa fenêtre :

{
  "detail": "Rate limit exceeded: 120 requests per 60 seconds"
}

Quand c'est le plafond de la marque qui refuse, la phrase le dit, elle donne le plafond de la marque, et elle précise que cette clef reste sous son propre plafond. L'en-tête X-RateLimit-Scope vaut alors brand.

Le dépassement du quota journalier prend une autre forme :

{
  "detail": "Quota exceeded. Remaining today: 0/1000"
}

#500, la panne est de notre côté

Votre requête n'a rien de fautif. Ne la corrigez pas. Relevez le X-Request-Id de la réponse, rejouez une fois après quelques secondes, et signalez-nous cet identifiant si le refus persiste.

Le corps d'un 500 n'a pas de forme garantie. N'écrivez aucune logique contre son contenu. Branchez-vous sur le statut 500 et sur rien d'autre.

{
  "detail": "Internal Server Error"
}

Sur une opération qui écrit, comme la frappe d'un lot, considérez le résultat comme inconnu. Rejouez avec la même valeur d'Idempotency-Key que le premier appel : soit le premier appel avait abouti et vous recevez sa réponse, soit il n'avait rien créé et le lot part.

#503, l'API refuse l'appel sans rien modifier

#Une réponse 200 peut vouloir dire non

Six points d'entrée répondent 200 sur un cas que vous devez traiter comme un refus. Un client qui ne regarde que le code HTTP les manque tous les six. Pour chacun, le champ à lire est nommé ci-dessous.

La vérification publique d'un QR. GET /qr/verify répond 200 avec "valid": false dans cinq situations. Le champ message dit laquelle s'applique. Lisez toujours valid.

{
  "valid": false,
  "message": "Invalid QR code signature. This QR code may be tampered with.",
  "uid_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "token_id": null,
  "product_name": null,
  "brand_name": null,
  "image_url": null,
  "contract_address": null,
  "scan_area": null
}

La vérification d'une signature d'originalité. POST /originality/read-sig/verify répond 200 avec "valid": false quand la signature lue sur la puce ne se vérifie pas contre la clef publique utilisée. Le champ error vaut alors signature invalide. Lisez valid.

La vérification d'intégrité d'un passeport. GET /passport/{identifier}/verify répond 200 même quand une comparaison échoue. Trois champs portent le résultat.

db_hash_match et ipfs_match valent true, false ou null. false veut dire que la comparaison a échoué. null veut dire qu'elle n'a pas pu être faite, ce qui est différent d'un échec.

seal.chain_link_match vaut true ou false, et il est absent du bloc seal quand la version du passeport n'a pas été scellée, ou quand elle a été scellée avant l'existence du chaînage. Lisez d'abord seal.sealed et seal.linked : quand les deux valent true, seal.chain_link_match est présent. C'est le champ qui dit si une version scellée a été modifiée après publication.

La vérification du justificatif vérifiable. GET /passport/{identifier}/vc/verify répond 200 avec "verified": false quand la signature du justificatif ne se vérifie pas contre la clef de la marque. Le champ error vaut alors verification_failed et credential_subject vaut null. Lisez verified.

Le suivi d'un lot. GET /v1/partner/mint/batch/status/{job_id} répond 200 avec "status": "unknown" quand le lot est introuvable, et 200 avec "status": "failed" quand il a échoué. Les valeurs que vous verrez sont queued, started, finished, failed et unknown. Bouclez sur status, et arrêtez-vous dès qu'il quitte queued et started. Ne bouclez pas sur is_finished : la réponse unknown ne porte que job_id et status, et une boucle qui attend is_finished ne s'arrêterait jamais.

La déclaration de vente. POST /v1/partner/sellout répond 200 avec "status": "already_activated" quand cet article avait déjà été déclaré vendu. Rien n'a été créé une seconde fois.

#Que rejouer, que ne pas rejouer

Un rejeu automatique se fait avec un délai qui croît, et un nombre d'essais borné. Rejouez sur 503, sur 500, et sur les 429 qui portent un Retry-After. Sur un 429 de quota journalier, arrêtez d'appeler jusqu'au changement de jour. Sur les autres codes 4xx, corrigez la requête avant tout nouvel appel.

#Une gestion d'erreur complète, en trois langages

Ces trois programmes font la même chose : ils déclarent une vente, ils distinguent les familles d'erreur, et ils gardent l'identifiant de requête.

Exécutez ces trois programmes sur votre serveur. L'API partenaire n'accepte pas d'appel venant d'un navigateur, et une clef d'API n'a rien à faire dans du code envoyé au navigateur. Depuis un navigateur, la lecture de X-Request-Id et celle de Retry-After rendraient null : ces deux en-têtes ne sont pas exposés au code de page.

#!/usr/bin/env bash
set -u

entetes=$(mktemp)
trap 'rm -f "$entetes"' EXIT

reponse=$(curl -sS -w '\n%{http_code}' -D "$entetes" \
  -X POST https://api.sealtrust.io/v1/partner/sellout \
  -H "Authorization: Bearer st_live_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"identifier": "DEM000000000", "retailer_code": "BTQ-EXEMPLE-01"}')

code=$(printf '%s' "$reponse" | tail -n 1)
corps=$(printf '%s' "$reponse" | sed '$d')
requete=$(grep -i '^x-request-id:' "$entetes" | tr -d '\r' | cut -d' ' -f2)

echo "code=$code request_id=$requete"
echo "$corps"

case "$code" in
  200) echo "vente enregistrée" ;;
  429|503) echo "réessayez plus tard" ;;
  5*) echo "panne serveur, signalez $requete" ;;
  *) echo "requête à corriger" ;;
esac

const reponse = await fetch("https://api.sealtrust.io/v1/partner/sellout", {
  method: "POST",
  headers: {
    Authorization:
      "Bearer st_live_0000000000000000000000000000000000000000000000",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    identifier: "DEM000000000",
    retailer_code: "BTQ-EXEMPLE-01",
  }),
});

const requestId = reponse.headers.get("X-Request-Id");
const corps = await reponse.json();

if (reponse.ok) {
  console.log("vente enregistrée", corps.status, requestId);
} else if (reponse.status === 429 || reponse.status === 503) {
  const attente = Number(reponse.headers.get("Retry-After") ?? 5);
  console.log("réessayez dans", attente, "secondes", requestId);
} else if (reponse.status >= 500) {
  console.log("panne serveur, signalez", requestId);
} else if (Array.isArray(corps.detail)) {
  for (const erreur of corps.detail) {
    console.log("champ refusé", erreur.loc.join("."), erreur.type);
  }
} else if (corps.detail && typeof corps.detail === "object") {
  console.log("refus code", corps.detail.code, requestId);
} else {
  console.log("refus", corps.detail, requestId);
}

import requests

reponse = requests.post(
    "https://api.sealtrust.io/v1/partner/sellout",
    headers={
        "Authorization": "Bearer st_live_0000000000000000000000000000000000000000000000",
        "Content-Type": "application/json",
    },
    json={"identifier": "DEM000000000", "retailer_code": "BTQ-EXEMPLE-01"},
    timeout=30,
)

request_id = reponse.headers.get("X-Request-Id")
corps = reponse.json()

if reponse.ok:
    print("vente enregistrée", corps["status"], request_id)
elif reponse.status_code in (429, 503):
    print("réessayez dans", reponse.headers.get("Retry-After", "5"), "secondes", request_id)
elif reponse.status_code >= 500:
    print("panne serveur, signalez", request_id)
else:
    detail = corps.get("detail")
    if isinstance(detail, list):
        for erreur in detail:
            print("champ refusé", ".".join(str(p) for p in erreur["loc"]), erreur["type"])
    elif isinstance(detail, dict):
        print("refus code", detail.get("code"), request_id)
    else:
        print("refus", detail, request_id)

#Ce qu'il faut retenir

• Le corps d'erreur porte toujours detail, sous trois formes : une phrase, un objet à code, ou une liste de valeurs refusées.
• Branchez votre code sur le statut HTTP et sur detail.code. Ne comparez jamais les phrases.
• Gardez le X-Request-Id de chaque échec. C'est ce que nous vous demanderons.
• Rejouez sur 503, sur 500, et sur les 429 qui portent un Retry-After. Corrigez sur tout le reste.
• Sur une écriture, rejouez avec la même valeur d'Idempotency-Key que l'appel dont vous ignorez le sort.
• Lisez valid, verified, status et les champs de correspondance : six points d'entrée décrivent un refus dans une réponse 200.