Diagnostiquer un transfert

Analyse l'état d'un transfert et explique pourquoi il échoue à travers une série de vérifications.

Réponse exemple

{
  "checks": [
    {
      "check": "lifecycle_status",
      "detail": "status = active",
      "status": "ok"
    },
    {
      "check": "expiration",
      "detail": "expired at 2026-06-01T12:00:00.000Z",
      "status": "fail"
    },
    {
      "check": "max_downloads",
      "detail": "5/5 downloads used",
      "status": "fail"
    },
    {
      "check": "scan_status",
      "detail": "scan_status = clean",
      "status": "ok"
    },
    {
      "check": "password_required",
      "detail": "Recipient must enter password",
      "status": "warn"
    }
  ],
  "verdict": "broken",
  "transfer_id": "f3a91c20-8b4e-4d7a-9c11-2e6f0a5b7d3e",
  "recommended_actions": [
    "coffrify_extend_transfer_expiry pour repousser l'expiration",
    "coffrify_clone_transfer pour repartir avec un compteur reset",
    "Vérifier que le destinataire a bien le mot de passe"
  ]
}

Cet endpoint répond à une seule question : pourquoi ce transfert échoue-t-il ? Il inspecte l'état d'un transfert appartenant à votre espace de travail et renvoie une liste de vérifications (checks) ciblées (statut de cycle de vie, expiration, quota de téléchargements, scan antivirus, protections par mot de passe/TOTP, restrictions géographiques), puis en déduit un verdict global et une liste d'actions recommandées. C'est un outil de diagnostic en lecture seule : il ne modifie jamais le transfert.

Le transfert est recherché à la fois par son identifiant (id dans le chemin) et par workspace_id, ce qui garantit qu'un transfert d'un autre espace de travail reste invisible (il renvoie alors une erreur not_found plutôt qu'un accès refusé).

GET/v1/diagnostics/transfer/{id}Diagnostique l'état d'un transfert et explique ses échecs.

Authentification

Requiert une clé API valide avec le scope transfers:read. La requête est soumise au rate-limiting par espace de travail (en-têtes X-RateLimit-* dans la réponse). Aucune clé d'idempotence n'est nécessaire : l'endpoint est en lecture seule (skipIdempotency).

Paramètres de chemin

Champ	Type	Requis	Description
id	string	Oui	Identifiant du transfert à diagnostiquer. Extrait du dernier segment de l'URL. Doit appartenir à l'espace de travail de la clé API.

Réponse

La réponse renvoie quatre champs : `transfer_id` (l'identifiant inspecté), `checks` (tableau de vérifications, chacune avec check, status valant ok, warn ou fail, et un detail lisible), `verdict` global, et `recommended_actions` (liste d'actions correctives suggérées en français).

check	Quand il apparaît	Statut possible
lifecycle_status	Toujours	ok (active), fail (deleted), warn (autre statut)
expiration	Si une date d'expiration est définie	ok (non expiré), fail (expiré)
max_downloads	Si un plafond de téléchargements est défini	ok (quota disponible), fail (quota atteint)
scan_status	Toujours	ok (clean ou null), fail (autre résultat de scan)
password_required	Si le transfert est protégé par mot de passe	warn
totp_required	Si le transfert exige un code TOTP	warn
geo_allowlist	Si une liste de pays autorisés est définie	warn
geo_blocklist	Si une liste de pays bloqués est définie	warn

Le `verdict` est calculé ainsi : broken si au moins une vérification est en fail, sinon degraded s'il existe au moins un warn, sinon healthy. Les `recommended_actions` ne sont peuplées qu'en présence d'échecs pertinents : expiration dépassée, quota de téléchargements atteint, scan antivirus en échec, ou protection par mot de passe active.

Erreurs

Code	Statut HTTP	Quand	Résolution
not_found	404	Aucun transfert avec cet id dans l'espace de travail de la clé.	Vérifiez l'identifiant et que le transfert appartient bien à votre espace de travail.
internal_error	500	Erreur lors de la lecture en base de données.	Réessayez ; si l'erreur persiste, contactez le support avec le request_id.
scope_missing	403	La clé API ne porte pas le scope transfers:read.	Émettez une clé incluant le scope transfers:read.
invalid_api_key	401	Clé API absente, invalide, expirée ou révoquée.	Vérifiez l'en-tête Authorization et l'état de la clé.
rate_limited	429	Quota de requêtes de l'espace de travail dépassé.	Respectez l'en-tête Retry-After avant de réessayer.

Voir aussi

POST /v1/transfers/{id}/extend pour repousser la date d'expiration d'un transfert expiré
POST /v1/transfers/{id}/clone pour recréer un transfert avec un compteur de téléchargements remis à zéro
POST /v1/transfers/{id}/rescan pour relancer le scan antivirus lorsque scan_status est en échec