Errors

L'API Products Manager retourne des erreurs structurées et prévisibles. Chaque réponse d'erreur suit un format JSON uniforme quel que soit l'endpoint ou le type de problème.

Format d'une Réponse d'Erreur

Toutes les erreurs retournent un objet JSON avec la structure suivante :

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "The requested product does not exist.",
    "details": {
      "product_id": 9999
    }
  }
}

Le champ details peut contenir des champs spécifiques selon l'erreur : identifiant de la ressource introuvable, champs en échec de validation, délai d'attente avant retry, etc.

Codes HTTP Utilisés

Codes d'Erreur Applicatifs

Authentification

Validation

Quotas Multi-tenant

Ressources Introuvables

Logique Métier

Rate Limiting

Exemples de Réponses d'Erreur

401 — Token expiré

{
  "error": {
    "code": "AUTH_TOKEN_EXPIRED",
    "message": "Access token has expired. Please refresh your token.",
    "details": {
      "expired_at": "2025-11-15T12:00:00Z"
    }
  }
}

403 — Permission insuffisante

{
  "error": {
    "code": "AUTH_INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to perform this action.",
    "details": {
      "required_permission": "products:delete",
      "user_role": "viewer"
    }
  }
}

422 — Erreur de validation (champs multiples)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation.",
    "details": {
      "fields": {
        "ean": "Invalid EAN-13 checksum.",
        "price": "Must be a positive number.",
        "name": "This field is required."
      }
    }
  }
}

409 — SKU dupliqué

{
  "error": {
    "code": "DUPLICATE_SKU",
    "message": "A product with SKU 'PROD-001' already exists in this catalog.",
    "details": {
      "sku": "PROD-001",
      "existing_product_id": 4821
    }
  }
}

403 — Quota dépassé

{
  "error": {
    "code": "QUOTA_PRODUCTS_EXCEEDED",
    "message": "Your plan allows a maximum of 10,000 products. Upgrade your plan to add more.",
    "details": {
      "current_count": 10000,
      "plan_limit": 10000,
      "plan": "starter",
      "upgrade_url": "https://productsmanager.app/billing/upgrade"
    }
  }
}

429 — Rate limit

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please wait before retrying.",
    "details": {
      "retry_after_seconds": 37,
      "limit": "100 requests per minute",
      "reset_at": "2025-11-15T10:31:00Z"
    }
  }
}

503 — Provider IA indisponible

{
  "error": {
    "code": "ENRICHMENT_PROVIDER_UNAVAILABLE",
    "message": "The AI enrichment provider is temporarily unavailable. Please retry in a few minutes.",
    "details": {
      "provider": "openai",
      "retry_after_seconds": 120
    }
  }
}

Gestion des Erreurs côté Client

Stratégie générale

• 4xx : erreurs client — corriger la requête avant de réessayer (sauf 429)
• 429 : attendre la durée indiquée dans Retry-After avant de réessayer
• 5xx : erreurs serveur — réessayer avec backoff exponentiel

Retry avec Backoff Exponentiel (429 et 503)

Pour les erreurs 429 Too Many Requests et 503 Service Unavailable, implémentez un backoff exponentiel avec jitter :

import time
import random

def request_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        response = fn()
        if response.status_code not in (429, 503):
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        jitter = random.uniform(0, 1)
        wait = retry_after + jitter
        time.sleep(wait)
    raise Exception("Max retries exceeded")

Idempotency Keys

Pour les opérations qui créent ou modifient des ressources (POST, PATCH), utilisez le header Idempotency-Key avec un UUID unique par tentative logique. Si la requête est rejouée avec la même clé dans les 24 heures, l'API retourne la réponse originale sans re-exécuter l'opération :

curl -X POST "https://api.productsmanager.app/api/v1/imports" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"supplier_id": 42, "file_url": "https://..."}'

Ceci est particulièrement utile pour les imports et les créations en masse afin d'éviter les doublons en cas de timeout réseau ou d'erreur transitoire.

Documentation Associée

• API Overview
• Authentification API
• Rate Limiting
• Exemples pratiques
• Permissions RBAC