En-têtes
Chaque en-tête de requête et de réponse de Noryo Merchant API, sa valeur, et sur quelles réponses il est présent.
Les noms d'en-têtes HTTP sont insensibles à la casse : l'API les écrit en minuscules dans ses réponses (noryo-request-id), la documentation les écrit avec des majuscules (Noryo-Request-Id). C'est le même en-tête.
En-têtes de requête
| En-tête | Routes | Obligatoire | Valeur |
|---|---|---|---|
Authorization | toutes | oui | Bearer nry_mer_<env>_<key_id>.<secret>. Voir Authentification. |
Content-Type | POST | oui | application/json. Un paramètre comme ; charset=utf-8 est accepté. Tout autre type rend 415. |
Idempotency-Key | POST /merchant/v1/enrichments | non, mais voir ci-dessous | 1 à 255 octets d'ASCII visible (0x21 à 0x7E), sans normalisation. |
Idempotency-Key | POST …/refresh | oui | Même format. Son absence rend 400 identifier_required. |
Précisions :
- Sur la création, l'
Idempotency-Keyest facultative à condition que le corps porte unexternal_transaction_id; sans aucun des deux, la requête est refusée en400 identifier_required. Voir Les deux identifiants. - Un en-tête
Idempotency-Keyprésent mais vide, trop long, contenant un espace ou un caractère hors de l'ASCII visible, ou répété, est refusé en400 invalid_idempotency_key. Sa forme est contrôlée sur toutes les routes, y comprisGET, où il n'a aucun effet. - Un
Noryo-Request-Idenvoyé par le client est ignoré et remplacé : vous ne choisissez pas l'identité Noryo de votre requête.
En-têtes de réponse
| En-tête | Présent sur | Valeur |
|---|---|---|
Noryo-Request-Id | toutes les réponses | req_<uuid>, l'identifiant de cette tentative. Identique au request_id du corps d'une erreur. Voir Identifiants de requête. |
Content-Type | toutes les réponses | application/json pour un succès, application/problem+json pour une erreur |
Cache-Control | toutes les réponses | no-store |
Noryo-Idempotency-Replayed | 200 des deux routes POST | true si la réponse vient de la mémoire d'idempotence, false sinon |
Noryo-RateLimit-Limit | 200 des trois routes, et 429 | La capacité de rafale du seau de votre clé |
Noryo-RateLimit-Remaining | 200 des trois routes, et 429 | Les jetons restant dans votre seau |
Retry-After | 429, 503 busy, 503 pricing_not_activated | Un nombre entier de secondes à attendre |
Location | 200 du rafraîchissement | Le chemin relatif du nouvel enrichissement, par exemple /merchant/v1/enrichments/enr_dd424f15-… |
WWW-Authenticate | 401, 403 insufficient_scope | Bearer realm="noryo-merchant-api", error="invalid_token" ou error="insufficient_scope" |
X-Content-Type-Options | toutes les réponses | nosniff |
Referrer-Policy | toutes les réponses | no-referrer |
X-Robots-Tag | toutes les réponses | noindex, nofollow |
Les réponses d'erreur autres que 429 ne portent pas les en-têtes Noryo-RateLimit-*, même quand elles ont consommé un jeton. Pour suivre votre solde, lisez-les sur vos réponses 200.
Location est relatif
Le rafraîchissement annonce le nouvel enrichment_id par un chemin relatif, jamais par une URL absolue : aucun nom d'hôte n'entre dans le contrat. Résolvez-le contre votre URL de base configurée.
Retry-After n'est posé que là où reprendre a un sens
Un Retry-After n'apparaît que sur les refus qu'une reprise de la même requête peut lever : la limite de débit, une contention passagère (busy), et une facturation pas encore activée (pricing_not_activated). Il n'apparaît jamais sur un 400 ou un 409. Voir Reprises.
Publié le 2026-10-09 10:18 UTC (version 2).