Riferimento

Errori e limiti

Codici di stato HTTP, formato errori, limiti di crediti e comportamento dei timeout su tutti gli endpoint dell'API Pedra.

Formato risposta di errore

Le richieste fallite restituiscono uno stato HTTP non-200 con un corpo JSON contenente un campo error che descrive cosa è andato storto.

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

Codici di stato

L'API Pedra usa un insieme volutamente piccolo di codici di stato. Niente 401 e niente 413 — una chiave API sconosciuta restituisce 404. Senza crediti si riceve 403 sugli endpoint di immagini, video e voce e 402 sugli endpoint dei tour virtuali. 429 si usa solo per i limiti giornalieri di caricamento e la registrazione tramite agente — non ci sono limiti al secondo o al minuto.

Stato
Significato
200
Successo. Gli endpoint immagini restituiscono output (array o singolo oggetto — vedi ogni endpoint); l'endpoint video restituisce videoId e una videoUrl pronta per lo streaming.
400
Richiesta non valida. Gli endpoint immagini la restituiscono quando imageUrl non restituisce un'immagine valida (risposta non-200, o byte che non sono un'immagine decodificabile). Restituito anche da /api/create_video per array images mancante, imageUrl mancante in un'immagine, valore effect non valido o effect: "transition" senza secondImageUrl.
402
Crediti insufficienti sugli endpoint dei tour virtuali (create_virtual_tour, add_virtual_tour_scenes). Il corpo contiene code: "insufficient_credits", creditsRequired, creditsAvailable e upgradeUrl. Non viene creato né addebitato nulla.
403
Crediti insufficienti sugli endpoint di immagini, video e voce. Il messaggio error spiega quanti crediti richiedeva la chiamata vs. quanti ne restano. Ricarica su app.pedra.ai o scrivi a felix@pedra.ai.
404
{"error": "User not found"} — la chiave API non corrispondeva a nessun account. È la risposta per chiavi mancanti, non valide o revocate.
405
Metodo non consentito. Tutti gli endpoint accettano solo POST.
429
È stato raggiunto un limite giornaliero. code indica quale: upload_limit (limite giornaliero di caricamento), upload_link_limit (link di caricamento al giorno) o rate_limited (registrazione tramite agente). Vedi Limite giornaliero di caricamento.
500
Errore del server. Mostra solitamente l'eccezione di elaborazione sottostante nel campo error.

Errori comuni

User not found (404)

La chiave API non corrispondeva a nessun account Pedra. Verifica che la chiave corrisponda a quella emessa e che sia nel corpo JSON come apiKey — non come header Authorization.

Insufficient credits (403 / 402)

Ogni piano include un'allocazione mensile di crediti — vedi pedra.ai/pricing. Gli endpoint immagini costano 1 credito; ogni frame video non statico costa 5. Quando finisci, ricevi un 403 con il calcolo esatto dei crediti (un 402 con creditsRequired e creditsAvailable sugli endpoint dei tour virtuali). Ricarica o cambia piano in app.pedra.ai → Impostazioni → Abbonamento e crediti.

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 video convalida effect rispetto all'insieme [zoom-in, zoom-out, transition, static]. Il messaggio di errore indica l'indice dell'immagine problematica.

imageUrl did not return a valid image (400)

L'imageUrl non puntava a un'immagine utilizzabile. O l'URL ha risposto con uno stato non-200 (spesso una pagina di errore HTML 404 servita su un URL .png), oppure i byte scaricati non erano un'immagine decodificabile. Apri l'URL in una finestra di navigazione privata per confermare che restituisca il file immagine reale — non una pagina di login, errore o segnaposto.

Image fetch failed (500)

Pedra non è riuscita a scaricare imageUrl entro 20 secondi. Cause: URL con autenticazione, URL prefirmato scaduto, origine lenta. Per URL prefirmati S3/R2/Cloudinary, invia l'immagine come URI data base64 data:image — Pedra userà i byte direttamente.

Limiti di velocità

Sull'API Pedra non ci sono limiti al secondo o al minuto. Il throughput è limitato dai crediti rimasti e dalla capacità di elaborazione sottostante. Gli unici limiti sono giornalieri: sulle foto che arrivano da fuori dall'app (sotto), sui link di caricamento e sulla registrazione tramite agente. Se esegui batch ad alto volume e ti serve un floor di throughput garantito, scrivi a felix@pedra.ai.

Limite giornaliero di caricamento

Ogni immagine salvata da fuori dall'app conta in una quota giornaliera per account: 30 al giorno sul piano gratuito, 500 al giorno sui piani a pagamento, azzerata a mezzanotte UTC. Cosa conta:

  • add_images_to_property (URL e URI data:)
  • Foto 360° passate tramite URL a create_virtual_tour e add_virtual_tour_scenes
  • File caricati tramite un link di caricamento e foto allegate in ChatGPT aggiunte a una proprietà

Le foto che modifichi tramite imageUrl e quelle caricate nell'app Pedra non contano. Oltre il limite, la chiamata restituisce 429 con code: "upload_limit" ed è rifiutata per intero — non viene salvato nulla. Gli elementi che falliscono da soli (un URL che non si carica, una foto che non è 360°) non contano. Ti serve più margine su un piano a pagamento? Scrivi 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"
}

Due limiti giornalieri collegati: upload_link_limit — 5 link di caricamento al giorno sul piano gratuito, 50 sui piani a pagamento (ogni link vale 24 ore, quindi riusalo); e rate_limited — richieste di registrazione tramite agente per indirizzo email e per IP.

Timeout

  • Download immagine: Pedra rinuncia dopo 20 secondi a scaricare imageUrl.
  • Endpoint immagini (enhance, furnish, empty_room, renovation, ecc.): risposta tipica 10–30 secondi.
  • Endpoint video: sincrono — si blocca durante il rendering del video, che può richiedere alcuni minuti. Imposta il timeout del client HTTP in modo generoso.

Riprovare in sicurezza

Tutti gli endpoint sono idempotenti all'interno di una richiesta — riprovare con lo stesso corpo produce una nuova generazione, mai uno stato corrotto. Le richieste fallite (4xx/5xx) non consumano crediti nella maggior parte dei percorsi; la deduzione dei crediti avviene all'interno del metodo Meteor una volta avviata l'elaborazione.

Hai bisogno di aiuto?

Scrivi a felix@pedra.ai con il corpo della richiesta fallita e la risposta. Rispondiamo entro un giorno lavorativo. Vedi Prezzi per le opzioni di crediti e quote.