Gestion des erreurs

L’API publique ANKK renvoie des codes d’état HTTP standard accompagnés de corps d’erreur JSON détaillés.

📌 Schéma d’erreur standard

Toutes les réponses d’erreur respectent le schéma suivant :

{
  "error": "idempotency_conflict",
  "message": "The idempotency key was already used with a different request payload.",
  "param": "idempotency_key"
}

🚦 Référence des codes d’état HTTP

Code d’état	Code d’erreur	Signification et action recommandée
`400 Bad Request`	`invalid_input`, `validation_failed`	Corps de requête ou paramètres mal formés. Corrigez le payload.
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	Clé API manquante ou invalide.
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	Portée (scope) manquante ou quota du forfait dépassé.
`404 Not Found`	`not_found`	Ressource (`content_id`, `connection_id`) introuvable.
`409 Conflict`	`idempotency_conflict`	Clé d’idempotence réutilisée avec un payload différent.
`423 Locked`	`brand_locked`	Marque verrouillée pour des raisons de facturation ou de politique. Consultez Facturation.
`429 Too Many Requests`	`rate_limited`	Limite de débit dépassée. Attendez selon le délai `Retry-After`.
`500 Server Error`	`internal_server_error`	Problème interne du serveur. Réessayable avec un délai d’attente exponentiel.
`503 Service Unavailable`	`sns_provider_unavailable`	Panne externe du réseau social. Réessayable plus tard.

🔍 Exemples d’erreurs métier courantes

1. 403 Portée insuffisante

{
  "error": "insufficient_scope",
  "message": "The API key does not have the required 'publishing:create' scope."
}

2. 409 Conflit d’idempotence

{
  "error": "idempotency_conflict",
  "message": "Idempotency key 'launch-001' is already bound to a different request hash.",
  "param": "idempotency_key"
}

3. 400 Échec de validation des médias

{
  "error": "sns_content_media_maximum_exceeded",
  "message": "Bluesky supports a maximum of 4 images per post.",
  "param": "media"
}

🔁 Stratégies de nouvelle tentative sûres

Réessayable (5xx, délais d’attente réseau) : Renvoyez la requête avec exactement la même clé d’idempotence, en appliquant un délai d’attente exponentiel et une variation aléatoire.
Nouvelle tentative impossible (400, 401, 403, 404, 409) : Corrigez le code client ou la charge utile, puis envoyez une nouvelle requête avec une autre clé d’idempotence.

🔗 Documentation connexe