Erreurs

Toutes les erreurs retournees par l'API suivent un format unifie.

Format d'erreur

{
  "status": "error",
  "code": "CODE_ERREUR",
  "description": "Message d'erreur lisible",
  "errors": ["detail1", "detail2"],
  "upstream": { ... }
}

Champ	Type	Presence	Description
status	string	Toujours	Toujours "error"
code	string	Toujours	Code machine (voir table ci-dessous)
description	string	Toujours	Message lisible
errors	array	VALIDATION_ERROR	Liste des erreurs de validation par champ
upstream	object	UPSTREAM_ERROR	Body brut retourne par l'API OPCO

Codes d'erreur

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	Non	Parametres ou body invalides
HTTP_ERROR	403	Non	Header X-API-KEY manquant ou authentification echouee
NOT_FOUND	404	Non	Ressource introuvable (OPCO, dossier, job, webhook, sync)
NOT_SUPPORTED	501	Non	Endpoint non supporte par cet OPCO
UPSTREAM_ERROR	Variable	Selon code	Erreur retournee par l'API OPCO sous-jacente
TIMEOUT	504	Oui	L'API OPCO n'a pas repondu dans le delai imparti
NETWORK_ERROR	502	Oui	Erreur reseau lors de la communication avec l'OPCO
INTERNAL_ERROR	500	Non	Erreur interne inattendue

Detail par code

VALIDATION_ERROR (400)

Erreur de validation des parametres de requete ou du body JSON. Le champ errors contient le detail par champ.

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "description": "Invalid request parameters",
  "errors": [
    "cerfa.employeur.siret: Required",
    "cerfa.contrat.dateDebutContrat: Invalid date"
  ]
}

Exemples de causes :

• Champ requis manquant
• Format de date invalide
• Enum non reconnue
• Parametres de recherche incompatibles (ex: numeroInterne + numeroExterne)

NOT_FOUND (404)

La ressource demandee n'existe pas, ou n'est pas accessible pour ce tenant.

{
  "status": "error",
  "code": "NOT_FOUND",
  "description": "Job '550e8400-...' introuvable"
}

NOT_SUPPORTED (501)

L'endpoint n'est pas supporte par l'OPCO demande (chaque OPCO a ses propres capacites).

{
  "status": "error",
  "code": "NOT_SUPPORTED",
  "description": "Endpoint 'GET /cfakeyinfo' non supporté par atlas"
}

UPSTREAM_ERROR (variable)

L'API OPCO a retourne une erreur. Le code HTTP est celui retourne par l'OPCO. Le champ upstream contient le body brut de l'OPCO.

{
  "status": "error",
  "code": "UPSTREAM_ERROR",
  "description": "OPCO returned 400",
  "upstream": {
    "errors": [
      { "code": 1234, "description": "SIRET inconnu" }
    ]
  }
}

Retryable si le code HTTP OPCO est 429, 503 ou >= 500.

TIMEOUT (504)

L'API OPCO n'a pas repondu dans le delai imparti. Retryable.

{
  "status": "error",
  "code": "TIMEOUT",
  "description": "OPCO request timed out after 30000ms"
}

NETWORK_ERROR (502)

Erreur reseau (DNS, connexion refusee, etc.). Retryable.

{
  "status": "error",
  "code": "NETWORK_ERROR",
  "description": "Network error: ECONNREFUSED"
}

INTERNAL_ERROR (500)

Erreur interne non prevue. Non retryable. Si persistante, contacter le support.

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "description": "An unexpected error occurred"
}

Strategie de retry

Pour les erreurs retryables (UPSTREAM_ERROR 429/5xx, TIMEOUT, NETWORK_ERROR) :

1. Jobs asynchrones : retries automatiques geres par Opcovia (BullMQ, backoff exponentiel)
2. Requetes synchrones : le client doit gerer ses propres retries avec backoff exponentiel

Backoff recommande : 1s, 2s, 4s, 8s (max 4 tentatives).