Erreurs, limites et versions

Tout ce que dit cette page vaut pour chaque endpoint de /v1 : un seul gestionnaire de votre côté lit tous les refus, et une seule politique de relance couvre tous les appels.

Une seule forme d’erreur

Quel que soit le statut, une erreur répond le même corps :

{
  "code": "not_found",
  "message": "no asset of this organization has this id",
  "request_id": "0192a6d3-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

• code est ce sur quoi votre code se branche. Un code garde son sens pour toujours, et la liste peut s’allonger : lisez un code inconnu d’après le statut HTTP qui l’accompagne.
• message est en anglais et s’adresse à une personne — journalisez-le, montrez-le à un développeur, ne vous branchez jamais dessus : il peut changer à tout moment.
• request_id identifie la requête : citez-le quand vous nous écrivez à propos d’un échec. Il est absent, jamais null, quand le serveur n’en a pas.

Statuts et codes

La référence de l’API liste, pour chaque endpoint, les refus qu’il peut répondre.

Un corps refusé : 415, 422 ou 400

Chaque corps est du JSON, sauf celui d’une vignette, qui est l’image elle-même. Un corps refusé l’est pour l’une de trois raisons, et chacune a son statut :

• 415 — il n’est pas envoyé sous le bon Content-Type : un corps JSON hors de application/json, une vignette hors de image/jpeg, image/png ou image/webp ;
• 422 — ce n’est pas la requête : un champ obligatoire manque, un champ a le mauvais type, ou le corps nomme un champ que la requête ne liste pas ;
• 400 — c’est bien la requête, mais une valeur est refusée par ses règles : trop longue, mal formée, contradictoire avec une autre. Le message nomme le champ.

L’API n’ignore pas ce qu’elle ne comprend pas : un champ inconnu dans un corps est refusé plutôt qu’ignoré, et de même pour un paramètre de requête — que l’endpoint ne connaît pas, ou donné deux fois (400). ?typ=video est refusé plutôt que servi sans filtre, et une écriture ne prend aucun paramètre de requête. Une faute de frappe est donc une erreur que vous voyez tout de suite, jamais un réglage ignoré en silence.

Un identifiant dans un corps : 404

Un identifiant envoyé dans un corps — un workspace, une chaîne, un asset, un champ personnalisé — qui ne désigne rien que votre clé puisse atteindre vaut un 404, qu’il ne désigne rien du tout ou quelque chose d’une autre organisation. C’est la même réponse que pour un identifiant dans le chemin.

Les catégories d’une publication font exception : une catégorie qui n’est pas de la chaîne de la publication est refusée par un 400, qui la nomme.

Les 403 qui ne sont pas une permission

Une clé qui porte la bonne permission peut quand même recevoir un 403 :

• l’organisation ne publie pas de chaînes : chaque endpoint des chaînes, des catégories et des publications répond 403 à toutes ses clés ;
• l’asset est validé dans le fonds commun de l’organisation : il est en lecture seule pour l’API, et chacune des requêtes qui le modifient répond 403, quelles que soient les permissions de la clé — seuls les modérateurs du fonds commun le modifient, depuis Videas. Voir Modifier un asset.

Ni l’un ni l’autre ne se relance.

Les 409

Un 409 dit que la requête contredit l’état de la ressource. Relire cet état dit quoi faire :

Relancer

• 429 : attendez le nombre de secondes que donne Retry-After, puis renvoyez la même requête.
• 500, 502, 503, 504 : relancez avec un délai croissant — un back-off exponentiel.
• Un GET se renvoie toujours sans risque, et un PATCH ou un PUT aussi : chacun dit ce que la ressource doit porter, et envoyé deux fois, le second la trouve déjà dans cet état et n’écrit rien.
• DELETE /v1/uploads/{upload_id} se renvoie sans risque : un upload déjà abandonné, expiré ou en échec répond 204 et reste tel quel.
• Un POST crée quelque chose : après une expiration ou une 5xx, cherchez ce que le premier a pu créer avant de le renvoyer.
  • POST /v1/uploads et POST /v1/assets ne sont pas idempotents : envoyés deux fois, ils créent deux assets. Renseignez external_ref à chaque fois, et cherchez-le avec GET /v1/assets?external_ref= avant de renvoyer — pour un fichier comme pour une vidéo hébergée ailleurs.
  • POST /v1/publications publie un asset une seule fois sur une chaîne : renvoyé, il répond 409, et GET /v1/publications?channel_id=…&asset_id=… retrouve la publication que le premier a créée.

Limites

Voici les limites que publie le contrat :

Au-delà, toute requête peut être refusée par un 429 quand une clé, ou son organisation, envoie plus que ce que l’API accepte : la réponse porte toujours Retry-After, et attendre ce délai est tout ce qu’elle demande.

Ce qui peut changer sous /v1

Sans nouvelle version, l’API peut gagner :

• un nouvel endpoint ;
• un nouveau paramètre de requête facultatif ;
• un nouveau champ dans une réponse ;
• une nouvelle valeur dans une liste de valeurs — le code d’une erreur ou d’un échec, le status d’un upload, et celles du tableau ci-dessous.

Écrivez votre client pour qu’il lise un champ ou une valeur inconnus comme quelque chose qu’il ne connaît pas encore, pas comme une erreur. Pour certaines listes, le contrat dit comment lire une valeur inconnue :

Jamais sous /v1 : retirer ou renommer quoi que ce soit, changer un type ou une unité, ou refuser une requête qui était acceptée. Ce serait une nouvelle version, /v2.

Pour aller plus loin

• Démarrer — une clé, ses permissions, et un premier appel.
• Lire la bibliothèque.
• Ajouter un fichier par l’API.
• Modifier un asset et publier sur une chaîne.