Référence

Erreurs et limites

Codes d'état HTTP, format des erreurs, limites de crédits et comportement des timeouts sur tous les endpoints de l'API Pedra.

Format de réponse d'erreur

Les requêtes échouées renvoient un statut HTTP non-200 avec un corps JSON contenant un champ error décrivant ce qui a mal tourné.

JSON

{
  "error": "User not found"
}

Codes d'état

L'API Pedra utilise un ensemble délibérément restreint de codes d'état. Pas de 401, pas de 429, pas de 413 — les erreurs d'authentification et de quota renvoient 404 et 403 respectivement, et il n'y a pas de limites de débit côté serveur aujourd'hui.

Statut

Signification

200

Succès. Les endpoints d'image renvoient output (tableau ou objet unique — voir chaque endpoint) ; l'endpoint vidéo renvoie videoId et une videoUrl prête à diffuser.

400

Mauvaise requête. Renvoyée par /api/create_video pour un tableau images manquant, un imageUrl manquant dans une image, une valeur effect invalide ou effect: "transition" sans secondImageUrl.

403

Crédits insuffisants. Le corps de l'erreur explique combien de crédits l'appel nécessitait vs combien restent. Rechargez sur app.pedra.ai ou écrivez à felix@pedra.ai.

404

{"error": "User not found"} — la clé API ne correspondait à aucun compte. C'est la réponse pour les clés manquantes, invalides ou révoquées.

405

Méthode non autorisée. Tous les endpoints n'acceptent que POST.

500

Erreur serveur. Expose le plus souvent l'exception de traitement sous-jacente dans le champ error. Pour l'endpoint vidéo, renvoyé aussi en cas de timeout interne de 10 minutes.

Erreurs courantes

`User not found` (404)

La clé API ne correspondait à aucun compte Pedra. Vérifiez que la clé correspond à celle que nous avons émise et qu'elle est dans le corps JSON sous apiKey — pas dans un en-tête Authorization.

`Insufficient credits` (403)

Chaque plan inclut une allocation mensuelle de crédits — voir pedra.ai/pricing. Les endpoints d'image coûtent 1 crédit ; chaque image vidéo non statique coûte 5. Quand vous êtes à court, vous recevez un 403 avec le calcul exact des crédits. Rechargez ou changez de plan sur app.pedra.ai → Paramètres → Abonnement et crédits.

`Invalid effect 'X' at index N` (400)

L'endpoint vidéo valide effect par rapport à l'ensemble [zoom-in, zoom-out, transition, static]. Le message d'erreur indique l'index de l'image fautive.

`Video processing timeout after 10 minutes` (500)

L'endpoint vidéo se bloque jusqu'à 10 minutes pendant le rendu. Si le rendu dépasse cette fenêtre, l'endpoint renvoie 500. La vidéo peut encore se terminer en arrière-plan — écrivez au support avec le corps de la requête pour récupérer l'URL finale.

`Image fetch failed` (500)

Pedra n'a pas pu télécharger imageUrl en 20 secondes. Causes : URL avec authentification, URL présignée expirée, origine lente. Pour les URLs présignées S3/R2/Cloudinary, envoyez l'image sous forme d'URI data base64 data:image — Pedra utilisera les octets directement.

Limites de débit

Il n'y a pas de limites par seconde ou par minute sur l'API Pedra aujourd'hui. Le débit est limité par vos crédits restants et la capacité de traitement sous-jacente. Si vous exécutez des lots à fort volume et avez besoin d'un débit minimum garanti, écrivez à felix@pedra.ai.

Timeouts

Téléchargement d'image : Pedra abandonne après 20 secondes en essayant de télécharger imageUrl.
Endpoints d'image (enhance, furnish, empty_room, renovation, etc.) : réponse typique 10–30 secondes.
Endpoint vidéo : se bloque jusqu'à 10 minutes. Configurez le timeout de votre client HTTP à au moins 11 minutes.

Réessayer en toute sécurité

Tous les endpoints sont idempotents au sein d'une requête — relancer avec le même corps produit une nouvelle génération, jamais un état corrompu. Les requêtes échouées (4xx/5xx) ne consomment pas de crédits dans la plupart des cas ; la déduction de crédits se fait dans la méthode Meteor une fois le traitement lancé.

Besoin d'aide ?

Écrivez à felix@pedra.ai avec le corps de la requête échouée et la réponse. Nous répondons sous un jour ouvré. Voir Tarification pour les options de crédits et de quotas.