Codes d'erreur

Référence pour tous les codes d'erreur retournés par les APIs ZYKAY.

Erreurs de l'API d'échange

Code	HTTP	Description	Solution
`MISSING_HEADERS`	401	Un ou plusieurs headers requis manquent	Incluez tous les headers : `X-Partner-ID`, `X-Partner-Timestamp`, `X-Partner-Nonce`, `X-Partner-Signature`
`INVALID_PARTNER`	403	Partner ID non reconnu	Vérifiez votre Partner ID
`TIMESTAMP_SKEW`	401	Timestamp décalé de plus de 5 minutes	Utilisez le timestamp Unix actuel en secondes, synchronisez l'horloge serveur
`INVALID_SIGNATURE`	401	La vérification de signature HMAC a échoué	Vérifiez le calcul de signature. IMPORTANT : Le partner secret est base64 et doit être décodé avant utilisation
`REPLAY_DETECTED`	401	Le nonce a déjà été utilisé	Utilisez un UUID v4 unique pour chaque requête
`INVALID_REQUEST`	400	Corps de requête invalide ou `grant_code` manquant	Vérifiez le format JSON et la présence du grant_code
`INVALID_GRANT`	400	Format de grant invalide	Le grant_code doit commencer par `g_`
`GRANT_INVALID`	401	Grant code inexistant ou expiré	Les grants expirent en 5 minutes et sont à usage unique
`INTERNAL_ERROR`	500	Erreur côté serveur	Réessayez avec backoff exponentiel

Erreurs de l'API d'introspection

Code	HTTP	Description	Solution
`INVALID_REQUEST`	400	`pass_token` manquant ou invalide	Vérifiez que le body contient `{"pass_token": "p_..."}`
`INTERNAL_ERROR`	500	Erreur côté serveur	Réessayez avec backoff exponentiel

Les erreurs de signature HMAC (MISSING_HEADERS, INVALID_SIGNATURE, etc.) sont identiques à celles de l'API d'échange ci-dessus.

Un token expiré ou invalide retourne un statut 200 avec {"active": false} (pas une erreur HTTP), conformément à la convention RFC 7662.

Erreurs Billing Session (ADULT_BLIND)

Ces erreurs sont retournées par POST /api/billing/session uniquement.

Code	HTTP	Description	Solution
`FORBIDDEN_RAIL`	403	L'organisation n'est pas sur le rail ADULT_BLIND	Contactez tech@zykay.com pour activer le rail
`MISSING_BLIND_APP_ID`	400	`blindAppId` non configuré pour l'organisation	Contactez le support ZYKAY
`MISSING_ORIGIN`	400	Le champ `origin` est absent du corps	Incluez `"origin": "https://votresite.com"` dans le body
`INVALID_SCOPES`	400	Scopes non supportés pour votre tier	Vérifiez les scopes disponibles pour votre niveau
`INVALID_JSON`	400	Corps JSON malformé	Vérifiez le format du body

Les erreurs HMAC (MISSING_HEADERS, INVALID_PARTNER, INVALID_SIGNATURE, etc.) sont identiques à celles de l'API d'échange.

Erreurs Loader v4 (frontend)

Le loader v4 n'utilise pas de postMessage d'erreur. Les erreurs passent par le callback onError :

Code	Description	Action
`INIT_FAILED`	Échec de création de verify-request	Vérifier `data-partner-id`, connectivité et CORS
`SERVER_VERIFY_TIMEOUT`	Timeout du mode `server-verify`	Vérifier votre endpoint `data-server-verify-endpoint`

Codes de statut HTTP

Statut	Signification
`200`	Succès
`400`	Mauvaise requête - Vérifier le corps de la requête
`401`	Non autorisé - Vérifier identifiants/signature
`404`	Non trouvé - Vérifier l'URL de l'endpoint
`429`	Trop de requêtes - Limite de débit atteinte (voir politique publiée)
`500`	Erreur interne du serveur - Réessayer plus tard

Politique 429 (résumé)

GET /api/w/verify-status/:requestId?pt=...: 30 req / 60s, renvoie Retry-After: 60
POST /api/partner/verify-request: 60 req / 60s
GET /api/partner/verify-status/:requestId: 60 req / 60s
POST /api/billing/session (pré-auth IP): 30 req / 60s
POST /api/billing/session (post-auth partenaire): 100 req / 60s

Référence complète: Politique de Rate-Limit

Gestion des erreurs (intégration recommandée)

async function callWithRetry(makeCall) {
  const delaysMs = [1000, 2000, 4000];
 
  for (let i = 0; i < delaysMs.length; i++) {
    const res = await makeCall();
    if (res.status !== 429) return res;
 
    const retryAfter = Number(res.headers.get('Retry-After') || '0');
    const waitMs = retryAfter > 0 ? retryAfter * 1000 : delaysMs[i];
    await new Promise((r) => setTimeout(r, waitMs));
  }
 
  throw new Error('Rate limit exceeded after retries');
}

Démarrage Rapide