Referencia

Errores y límites

Códigos de estado HTTP, formato de errores, límites de créditos y comportamiento ante timeouts en todos los endpoints de la API de Pedra.

Formato de respuesta de error

Las peticiones fallidas devuelven un estado HTTP distinto de 200 con un cuerpo JSON que contiene un campo error describiendo qué fue mal.

JSON
{
  "error": "User not found"
}

Códigos de estado

La API de Pedra usa un conjunto pequeño de códigos de estado a propósito. No hay 401 ni 413 — una clave API desconocida devuelve 404. Quedarse sin créditos devuelve 403 en los endpoints de imagen, vídeo y voz y 402 en los endpoints de tours virtuales. 429 solo se usa para los límites diarios de subida y el registro de agentes — no hay límites por segundo ni por minuto.

Estado
Significado
200
Éxito. Los endpoints de imagen devuelven output (array u objeto único — mira cada endpoint); el endpoint de vídeo devuelve videoId y una videoUrl lista para reproducir.
400
Petición incorrecta. Los endpoints de imagen la devuelven cuando imageUrl no devuelve una imagen válida (respuesta distinta de 200, o bytes que no son una imagen decodificable). También la devuelve /api/create_video cuando falta el array images, falta imageUrl en alguna imagen, hay un valor de effect inválido o effect: "transition" sin secondImageUrl.
402
Créditos insuficientes en los endpoints de tours virtuales (create_virtual_tour, add_virtual_tour_scenes). El cuerpo trae code: "insufficient_credits", creditsRequired, creditsAvailable y upgradeUrl. No se crea ni se cobra nada.
403
Créditos insuficientes en los endpoints de imagen, vídeo y voz. El mensaje de error explica cuántos créditos requería la llamada vs. cuántos quedan. Recarga en app.pedra.ai o escribe a felix@pedra.ai.
404
{"error": "User not found"} — la clave API no coincidió con ninguna cuenta. Es la respuesta para claves faltantes, inválidas o revocadas.
405
Método no permitido. Todos los endpoints aceptan solo POST.
429
Se alcanzó un límite diario. code indica cuál: upload_limit (límite diario de subidas), upload_link_limit (enlaces de subida por día) o rate_limited (registro de agentes). Mira Límite diario de subidas.
500
Error del servidor. Normalmente expone la excepción de procesamiento subyacente en el campo error.

Errores comunes

User not found (404)

La clave API no coincidió con ninguna cuenta de Pedra. Verifica que la clave coincide con la que emitimos y que está en el cuerpo JSON como apiKey — no como cabecera Authorization.

Insufficient credits (403 / 402)

Cada plan incluye una asignación mensual de créditos — mira pedra.ai/pricing. Los endpoints de imagen cuestan 1 crédito; cada frame de vídeo no estático cuesta 5. Cuando te quedes sin créditos, recibirás un 403 con el cálculo exacto (un 402 con creditsRequired y creditsAvailable en los endpoints de tours virtuales). Recarga o cambia de plan en app.pedra.ai → Ajustes → Suscripción y créditos.

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)

El endpoint de vídeo valida effect contra el conjunto [zoom-in, zoom-out, transition, static]. El mensaje de error indica el índice de la imagen problemática.

imageUrl did not return a valid image (400)

La imageUrl no apuntaba a una imagen utilizable. O bien la URL respondió con un estado distinto de 200 (a menudo una página de error HTML 404 servida en una URL .png), o los bytes descargados no eran una imagen decodificable. Abre la URL en una ventana de incógnito para confirmar que devuelve el archivo de imagen real — no una página de login, error o marcador.

Image fetch failed (500)

Pedra no pudo descargar la imageUrl en 20 segundos. Causas: URL con autenticación, URL pre-firmada caducada, origen lento. Para URLs pre-firmadas de S3/R2/Cloudinary, envía la imagen como data URI base64 data:image — Pedra usará los bytes directamente.

Límites de tasa

En la API de Pedra no hay límites por segundo ni por minuto. El throughput está limitado por tus créditos restantes y la capacidad de procesamiento subyacente. Los únicos límites son diarios: en las fotos que entran desde fuera de la app (abajo), en los enlaces de subida y en el registro de agentes. Si vas a hacer lotes de alto volumen y necesitas un mínimo garantizado, escribe a felix@pedra.ai.

Límite diario de subidas

Cada imagen que se guarda desde fuera de la app cuenta para un cupo diario por cuenta: 30 al día en el plan gratuito, 500 al día en los planes de pago, que se reinicia a medianoche UTC. Qué cuenta:

  • add_images_to_property (URLs y URIs data:)
  • Fotos 360° enviadas por URL a create_virtual_tour y add_virtual_tour_scenes
  • Archivos subidos con un enlace de subida y fotos adjuntadas en ChatGPT que se añaden a una propiedad

Las fotos que editas por imageUrl y las que se suben en la app de Pedra no cuentan. Si superas el límite, la llamada devuelve 429 con code: "upload_limit" y se rechaza entera — no se guarda nada. Los elementos que fallan por sí solos (una URL que no carga, una foto que no es 360°) no cuentan. ¿Necesitas más margen en un plan de pago? Escribe a 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"
}

Dos límites diarios relacionados: upload_link_limit — 5 enlaces de subida al día en el plan gratuito, 50 en los de pago (cada enlace funciona 24 horas, así que reutilízalo); y rate_limited — solicitudes de registro de agentes por dirección de email y por IP.

Timeouts

  • Descarga de imagen: Pedra abandona tras 20 segundos intentando descargar la imageUrl.
  • Endpoints de imagen (enhance, furnish, empty_room, renovation, etc.): respuesta típica de 10–30 segundos.
  • Endpoint de vídeo: síncrono — bloquea mientras se renderiza el vídeo, lo que puede tardar varios minutos. Configura el timeout del cliente HTTP de forma generosa.

Reintentos seguros

Todos los endpoints son idempotentes dentro de una petición — reintentar con el mismo cuerpo produce una nueva generación, nunca un estado corrupto. Las peticiones fallidas (4xx/5xx) no consumen créditos en la mayoría de rutas; la deducción de créditos ocurre dentro del método Meteor cuando empieza el procesamiento.

¿Necesitas ayuda?

Escribe a felix@pedra.ai con el cuerpo de la petición fallida y la respuesta. Contestamos en un día laborable. Mira Precios para opciones de créditos y cuotas.