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 429, ni 413 — los errores de autenticación y cuota devuelven 404 y 403 respectivamente, y hoy no hay límites de tasa del lado del servidor.

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. 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.
403
Créditos insuficientes. El cuerpo del 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.
500
Error del servidor. Normalmente expone la excepción de procesamiento subyacente en el campo error. Para el endpoint de vídeo, también se devuelve cuando se alcanza el timeout interno de 10 minutos.

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)

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. Recarga o cambia de plan en app.pedra.ai → Ajustes → Suscripción y créditos.

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.

Video processing timeout after 10 minutes (500)

El endpoint de vídeo bloquea hasta 10 minutos mientras renderiza. Si el renderizado supera esa ventana, el endpoint devuelve 500. El vídeo puede completarse en segundo plano — escribe a soporte con el cuerpo de la petición para recuperar la URL final.

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

Hoy no hay límites por segundo o por minuto en la API de Pedra. El throughput está limitado por tus créditos restantes y la capacidad de procesamiento subyacente. Si vas a hacer lotes de alto volumen y necesitas un mínimo garantizado, escribe a felix@pedra.ai.

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: bloquea hasta 10 minutos. Configura el timeout del cliente HTTP a al menos 11 minutos.

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.