Erreurs et limites

Toutes les erreurs ont le même format, avec un code stable que votre programme peut tester. Les limites de débit et l’idempotence permettent de réessayer sans risque.

Format des erreurs

JSON

{ "error": { "code": "not_found", "message": "Video not found." } }

Testez code, pas message : le message peut évoluer. Chaque réponse porte un en-tête X-Request-Id ; indiquez-le au support.

Statut	Codes	Que faire
400	`invalid_request`	Corriger la requête (le message précise le champ)
401	`unauthorized`	Clé absente, invalide, révoquée ou expirée
402	`quota_exceeded`	Quota de l’organisation atteint : libérer de l’espace ou changer de palier
403	`insufficient_scope`, `organization_suspended`, `organization_closed`	Ajouter la permission à la clé, ou contacter Vidoum
404	`not_found`	Ressource absente, y compris si elle appartient à une autre organisation
409	`invalid_state`, `not_ready`, `upload_missing`, `idempotency_in_progress`, `limit_reached`	L’état actuel ne permet pas l’action : relire la ressource
422	`idempotency_mismatch`	Même clé d’idempotence avec un autre corps : utiliser une nouvelle clé
429	`rate_limited`	Attendre la durée indiquée par Retry-After
500, 503	`internal_error`, `edge_unavailable`	Réessayer avec un délai croissant

Limites de débit

600 requêtes par minute et par clé, dont 60 créations d’envoi par minute. Chaque réponse indique RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (en secondes). Une réponse 429 ajoute Retry-After. Le SDK attend et réessaie automatiquement.

Idempotence

Les routes de création acceptent un en-tête Idempotency-Key (une valeur unique de 255 caractères au plus, par exemple un UUID) : POST /v1/uploads, /v1/uploads/{id}/complete, /v1/videos/{id}/retry, /v1/webhooks et /v1/api-keys/rotate.

Même clé, même corps : la première réponse est renvoyée pendant 24 heures, avec l’en-tête Idempotent-Replayed: true. Une clé API ou un secret de webhook n’est jamais renvoyé une seconde fois : il vaut null dans la réponse rejouée, avec l’en-tête Idempotent-Secret-Redacted: true. S’il a été perdu, faites-en tourner un nouveau.
Même clé, autre corps : 422. Requête identique encore en cours : 409.
Une erreur serveur libère la clé : vous pouvez réessayer avec la même.

Utilisez une nouvelle clé pour chaque nouvelle intention, et la même pour réessayer après une coupure réseau.

Pagination

Les listes renvoient nextCursor. Repassez-le dans ?cursor= jusqu’à ce qu’il vaille null. limit : 200 vidéos au plus (50 par défaut), 100 envois de webhook au plus (25 par défaut).

Terminal

curl "https://api.vidoum.com/v1/videos?limit=100&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $VIDOUM_API_KEY"