Erreurs

Chaque erreur, sur chaque endpoint, utilise une seule enveloppe :

{
  "error": {
    "code": "not_found",
    "message": "Link not found",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

Branchez sur error.code, affichez error.message aux humains. Les erreurs de validation ajoutent un tableau details avec un message par champ :

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation",
    "doc_url": "https://linkprofit.com/docs/api/errors",
    "details": [
      { "path": "url", "message": "Destination URL is not a valid address" }
    ]
  }
}

Codes d’erreur

| Code | HTTP | Signification | Que faire | |---|---|---|---| | unauthorized | 401 | Clé absente, inconnue, révoquée ou expirée | Vérifiez l’en-tête ; émettez une nouvelle clé | | forbidden | 403 | Mauvais type de clé pour l’endpoint, ou opération non autorisée | Utilisez une clé d’espace de travail / partenaire, comme documenté | | insufficient_scope | 403 | La clé n’a pas une portée requise | Créez une clé avec la portée nommée dans le message | | plan_restricted | 403 | Le forfait n’inclut pas cette capacité | Passez au forfait supérieur ou retirez la fonction de la requête | | not_found | 404 | La ressource n’existe pas — ou appartient à un autre locataire | Vérifiez l’identifiant ; les ressources d’autrui sont indiscernables des ressources absentes | | invalid_request | 400 | JSON mal formé, curseur invalide, règle métier enfreinte | Corrigez la requête | | validation_failed | 422 | Le corps ou la requête a échoué à la validation de schéma | Corrigez les champs listés dans details | | conflict | 409 | Conflit d’état : slug déjà pris, Idempotency-Key réutilisée avec un corps différent | Choisissez une autre valeur ou une nouvelle clé d’idempotence | | quota_exceeded | 422 | Un quota du forfait est épuisé (liens, domaines, clients) | Passez au forfait supérieur ou libérez du quota | | rate_limited | 429 | Trop de requêtes pour cette clé | Attendez Retry-After secondes ; voir Limites de débit | | not_configured | 503 | La capacité n’est pas configurée dans cet environnement | Réessayez plus tard ou contactez le support | | internal | 500/502/504 | Erreur inattendue de la plateforme | Réessayez avec un délai croissant ; signalez si cela persiste | | invalid_click_id | 422 | Le click_id est contrefait, altéré ou émis dans un autre espace de travail | Transmettez la valeur du paramètre d’identifiant de clic exactement telle qu’elle apparaissait dans l’adresse de destination | | attribution_expired | 422 | Le clic est plus ancien que la fenêtre d’attribution de l’espace de travail | Rien à réessayer ; ajustez la fenêtre dans le tableau de bord si nécessaire |

Des règles de traitement qui paient

• Un 404 est aussi une isolation. Un identifiant appartenant à un autre espace de travail répond not_found, jamais forbidden — l’API ne révèle pas si un identifiant étranger existe.
• Ne réessayez que ce qui est sûr. Réessayez internal et rate_limited avec un délai croissant. Ne réessayez jamais aveuglément conflict ou validation_failed — c’est la requête elle-même qui est fausse. Utilisez Idempotency-Key pour rendre les mutations sûres à réessayer.
• GET /links ne renvoie jamais 404. Des filtres sans résultat renvoient une liste vide ; un 404 sur la collection serait ambigu.