Codes d'erreur

Toute réponse d'erreur de l'API partenaire est un Problem Details au sens de la RFC 7807, servi avec le Content-Type: application/problem+json.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://docs.pesia.fr/partner/errors/insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "detail": "An error occurred.",
  "code": "insufficient_scope",
  "missing": ["dpae:write"],
  "instance": "/partner/v1/dpae/submissions",
  "timestamp": "2026-08-14T09:12:44.318Z"
}

Les champs

Champ	Toujours présent	Contenu
`type`	oui	URL de cette documentation, propre au code. Identifiant stable : la même valeur en sandbox et en production.
`title`	oui	Libellé court, lisible. Non stable — ne branchez pas dessus.
`status`	oui	Statut HTTP, identique à celui de la réponse.
`detail`	oui	Message lisible propre à cette occurrence. Non stable — ne branchez pas dessus.
`code`	oui	Identifiant machine. C'est le seul champ sur lequel brancher votre logique.
`instance`	oui	Chemin de la requête à l'origine de l'erreur.
`timestamp`	oui	Horodatage ISO 8601 de la réponse.
`correlationId`	selon la requête	Reprend votre header `X-Correlation-Id` quand vous en envoyez un. À citer si vous nous contactez.

Certains codes ajoutent des extensions — des champs supplémentaires documentés sur la page du code concerné (par exemple missing pour insufficient_scope).

Brancher votre code

Utilisez code, jamais title ni detail :

curl -s -X POST https://api.pesia.fr/partner/v1/dpae/submissions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @submission.json \
| jq -r '.code // "ok"'

type est un identifiant stable, pas une adresse : sa valeur est identique dans tous les environnements. Traitez-la comme une chaîne de comparaison, et suivez le lien uniquement pour lire cette documentation.

Un code que vous ne connaissez pas peut apparaître : de nouveaux codes sont ajoutés au fil des fonctionnalités. Prévoyez un cas par défaut qui se rabat sur status.

Erreurs générales

Ces codes peuvent apparaître sur n'importe quel endpoint.

Code	Statut	Quand
`unauthorized`	401	Jeton d'accès absent, mal formé, expiré ou invalide.
`insufficient_scope`	403	Le jeton n'a pas le scope requis par l'endpoint.
`forbidden`	403	Accès refusé sans cause plus précise.
`not_found`	404	Chemin inconnu, ressource hors de votre périmètre, ou date sans barème SMIC.
`validation_error`	400	Le corps ou les paramètres de la requête ne respectent pas le schéma.
`idempotency_key_required`	400	Header `Idempotency-Key` absent sur une requête mutante.
`idempotency_key_invalid_format`	400	`Idempotency-Key` n'est ni un UUIDv4 ni un ULID.
`idempotency_key_conflict`	409	La clé a déjà servi pour une requête au corps différent.
`conflict`	409	Conflit d'état sans cause plus précise.
`unprocessable`	422	Requête bien formée mais métier impossible, sans cause plus précise.
`rate_limited`	429	Quota de requêtes dépassé.
`webhook_subscription_duplicate`	409	Une subscription existe déjà pour cette URL dans cet environnement.
`webhook_subscription_has_deliveries`	409	L'abonnement a encore des livraisons : supprimez-les d'abord.
`webhook_subscription_limit_reached`	422	Nombre maximal de subscriptions actives atteint.
`internal_error`	500	Erreur inattendue côté Pesia.

DPAE

Voir DPAE pour le détail des endpoints.

Code	Statut	Quand
`DPAE_AGENCY_NOT_FOUND`	404	Le code d'agence envoyé n'existe pas dans votre organisation.
`DPAE_AGENCY_PROFILE_INCOMPLETE`	400	L'agence n'a pas les informations légales nécessaires pour déclarer.
`DPAE_MANDATE_MISSING`	422	Le mandat de déclaration URSSAF de l'agence n'est pas actif.
`DPAE_SUBMISSION_NOT_FOUND`	404	La soumission demandée n'existe pas ou n'appartient pas à votre organisation ou à votre environnement.
`DPAE_NOT_CANCELLABLE`	409	L'envoi a commencé (dès `SENDING`) ou la soumission ne peut plus être annulée.
`DPAE_UPSTREAM_UNAVAILABLE`	503	Le service de déclarations est momentanément indisponible.

Lots de paie

Voir Lots de paie pour le détail des endpoints.

Code	Statut	Quand
`PARTNER_PAYROLL_BATCH_AGENCY_NOT_FOUND`	404	Le code d'agence envoyé n'existe pas dans votre organisation.
`PARTNER_PAYROLL_BATCH_AGENCY_INCOMPLETE`	400	L'agence n'a pas les informations légales ou les paramètres de paie nécessaires.
`PARTNER_PAYROLL_BATCH_INVALID_INPUT`	400	Le contexte de paie de l'agence est refusé : donnée de la fiche légale absente, ou aucun taux AT/MP intérimaire en vigueur pour la période.
`PARTNER_PAYROLL_BATCH_LOT_CLOSED`	409	Le lot de la période visée est clôturé.
`PARTNER_PAYROLL_BATCH_NOT_FOUND`	404	Le lot demandé n'existe pas ou n'appartient pas à votre organisation.

SMIC

Code	Statut	Quand
`SMIC_UPSTREAM_UNAVAILABLE`	503	Le barème SMIC est momentanément indisponible.

Codes de résultat par élément

Les endpoints qui traitent plusieurs éléments en une requête (dépôt de DPAE, soumission d'un lot de paie) répondent en 2xx même quand certains éléments échouent. Ces échecs sont portés par le corps de la réponse, élément par élément — ils ne sont pas des Problem Details et n'ont pas de page ici. Voir DPAE et Lots de paie.

Voir aussi : Authentification · Scopes · Idempotence · Stabilité du contrat

Les champs​

Brancher votre code​

Erreurs générales​

DPAE​

Lots de paie​

SMIC​

Codes de résultat par élément​