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 ni de 413 — une clé API inconnue renvoie 404. Un manque de crédits renvoie 403 sur les endpoints d'image, de vidéo et de voix, et 402 sur les endpoints de visites virtuelles. 429 ne sert qu'aux limites quotidiennes de téléversement et à l'inscription par agent — il n'y a pas de limite par seconde ni par minute.

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. Les endpoints d'image la renvoient quand imageUrl ne renvoie pas une image valide (réponse non-200, ou octets qui ne sont pas une image décodable). Également 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.
402
Crédits insuffisants sur les endpoints de visites virtuelles (create_virtual_tour, add_virtual_tour_scenes). Le corps contient code: "insufficient_credits", creditsRequired, creditsAvailable et upgradeUrl. Rien n'est créé ni facturé.
403
Crédits insuffisants sur les endpoints d'image, de vidéo et de voix. Le message error 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.
429
Une limite quotidienne est atteinte. code précise laquelle : upload_limit (limite quotidienne de téléversement), upload_link_limit (liens de téléversement par jour) ou rate_limited (inscription par agent). Voir Limite quotidienne de téléversement.
500
Erreur serveur. Expose le plus souvent l'exception de traitement sous-jacente dans le champ error.

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 / 402)

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 (un 402 avec creditsRequired et creditsAvailable sur les endpoints de visites virtuelles). Rechargez ou changez de plan sur app.pedra.ai → Paramètres → Abonnement et crédits.

JSON
{
  "error": "Insufficient credits. You need 5 credits but only have 2 remaining. Please purchase more credits at app.pedra.ai or contact felix@pedra.ai for support."
}

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.

imageUrl did not return a valid image (400)

L'imageUrl ne pointait pas vers une image utilisable. Soit l'URL a répondu avec un statut non-200 (souvent une page d'erreur HTML 404 servie sur une URL .png), soit les octets téléchargés n'étaient pas une image décodable. Ouvrez l'URL dans une fenêtre de navigation privée pour confirmer qu'elle renvoie le vrai fichier image — pas une page de connexion, d'erreur ou un placeholder.

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. Le débit est limité par vos crédits restants et la capacité de traitement sous-jacente. Les seules limites sont quotidiennes : sur les photos importées de l'extérieur de l'app (ci-dessous), sur les liens de téléversement et sur l'inscription par agent. Si vous exécutez des lots à fort volume et avez besoin d'un débit minimum garanti, écrivez à felix@pedra.ai.

Limite quotidienne de téléversement

Chaque image stockée depuis l'extérieur de l'app compte dans un quota quotidien par compte : 30 par jour sur le plan gratuit, 500 par jour sur les plans payants, remis à zéro à minuit UTC. Ce qui compte :

  • add_images_to_property (URL et URI data:)
  • Photos 360° passées par URL à create_virtual_tour et add_virtual_tour_scenes
  • Fichiers envoyés via un lien de téléversement et photos jointes dans ChatGPT puis ajoutées à une propriété

Les photos éditées via imageUrl et celles téléversées dans l'app Pedra ne comptent pas. Au-delà de la limite, l'appel renvoie 429 avec code: "upload_limit" et est refusé en entier — rien n'est stocké. Les éléments qui échouent d'eux-mêmes (une URL qui ne charge pas, une photo qui n'est pas en 360°) ne comptent pas. Besoin de plus sur un plan payant ? Écrivez à felix@pedra.ai.

JSON
{
  "error": "Daily upload limit reached (30 images per day on this plan). It resets at midnight UTC. Paid plans have a higher limit: https://www.pedra.ai/pricing",
  "code": "upload_limit"
}

Deux limites quotidiennes liées : upload_link_limit — 5 liens de téléversement par jour sur le plan gratuit, 50 sur les plans payants (chaque lien fonctionne 24 heures, réutilisez-le) ; et rate_limited — demandes d'inscription par agent par adresse e-mail et par IP.

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 : synchrone — se bloque pendant le rendu de la vidéo, ce qui peut prendre plusieurs minutes. Configurez le timeout de votre client HTTP de manière généreuse.

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.