Referenz

Fehler und Limits

HTTP-Statuscodes, Fehlerformate, Credit-Limits und Timeout-Verhalten über alle Pedra-API-Endpunkte hinweg.

Fehlerantwortformat

Fehlgeschlagene Anfragen geben einen Nicht-200-HTTP-Status mit einem JSON-Body zurück, der ein error-Feld mit der Fehlerbeschreibung enthält.

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

Statuscodes

Die Pedra-API verwendet absichtlich eine kleine Menge von Statuscodes. Es gibt kein 401 und kein 413 — ein unbekannter API-Schlüssel liefert 404. Fehlende Credits liefern 403 bei den Bild-, Video- und Voice-Endpunkten und 402 bei den Endpunkten für virtuelle Rundgänge. 429 gibt es nur für die täglichen Upload-Limits und die Agent-Registrierung — es gibt keine Limits pro Sekunde oder Minute.

Status
Bedeutung
200
Erfolg. Bild-Endpunkte geben output zurück (Array oder einzelnes Objekt — siehe jeweiligen Endpunkt); der Video-Endpunkt gibt videoId und eine streamfähige videoUrl zurück.
400
Ungültige Anfrage. Bild-Endpunkte geben dies zurück, wenn imageUrl kein gültiges Bild liefert (Nicht-200-Antwort oder Bytes, die kein dekodierbares Bild sind). Wird außerdem von /api/create_video zurückgegeben bei fehlendem images-Array, fehlendem imageUrl in einem Bild, ungültigem effect-Wert oder effect: "transition" ohne secondImageUrl.
402
Nicht genügend Credits bei den Endpunkten für virtuelle Rundgänge (create_virtual_tour, add_virtual_tour_scenes). Der Body enthält code: "insufficient_credits", creditsRequired, creditsAvailable und upgradeUrl. Es wird nichts erstellt oder berechnet.
403
Nicht genügend Credits bei den Bild-, Video- und Voice-Endpunkten. Die error-Meldung erklärt, wie viele Credits der Aufruf benötigte vs. wie viele übrig sind. Aufladen auf app.pedra.ai oder E-Mail an felix@pedra.ai.
404
{"error": "User not found"} — der API-Schlüssel passte zu keinem Konto. Das ist die Antwort für fehlende, ungültige oder widerrufene Schlüssel.
405
Methode nicht erlaubt. Alle Endpunkte akzeptieren nur POST.
429
Ein Tageslimit wurde erreicht. code sagt, welches: upload_limit (tägliches Upload-Limit), upload_link_limit (Upload-Links pro Tag) oder rate_limited (Agent-Registrierung). Siehe Tägliches Upload-Limit.
500
Serverfehler. Zeigt meist die zugrundeliegende Verarbeitungsausnahme im error-Feld.

Häufige Fehler

User not found (404)

Der API-Schlüssel passte zu keinem Pedra-Konto. Stellen Sie sicher, dass der Schlüssel mit dem ausgegebenen übereinstimmt und sich im JSON-Body als apiKey befindet — nicht als Authorization-Header.

Insufficient credits (403 / 402)

Jeder Tarif beinhaltet ein monatliches Credit-Kontingent — siehe pedra.ai/pricing. Bild-Endpunkte kosten 1 Credit; jeder nicht-statische Video-Frame kostet 5. Wenn Sie aufgebraucht sind, erhalten Sie ein 403 mit der genauen Credit-Berechnung (ein 402 mit creditsRequired und creditsAvailable bei den Rundgang-Endpunkten). Aufladen oder Tarif wechseln unter app.pedra.ai → Einstellungen → Abonnement und Credits.

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)

Der Video-Endpunkt validiert effect gegen die Menge [zoom-in, zoom-out, transition, static]. Die Fehlermeldung nennt den Bild-Index, der den Fehler verursacht.

imageUrl did not return a valid image (400)

Die imageUrl verwies nicht auf ein verwendbares Bild. Entweder antwortete die URL mit einem Nicht-200-Status (häufig eine 404-HTML-Fehlerseite unter einer .png-URL) oder die heruntergeladenen Bytes waren kein dekodierbares Bild. Öffnen Sie die URL in einem privaten Browserfenster, um zu bestätigen, dass sie die echte Bilddatei zurückgibt — keine Login-, Fehler- oder Platzhalterseite.

Image fetch failed (500)

Pedra konnte die imageUrl nicht innerhalb von 20 Sekunden herunterladen. Ursachen: Auth-geschützte URL, abgelaufene vorsignierte URL, langsame Quelle. Für vorsignierte S3/R2/Cloudinary-URLs senden Sie das Bild stattdessen als data:image-base64-URI — Pedra verwendet die Bytes direkt.

Rate-Limits

Es gibt keine Rate-Limits pro Sekunde oder Minute in der Pedra-API. Der Durchsatz wird durch Ihre verbleibenden Credits und die zugrundeliegende Verarbeitungskapazität begrenzt. Die einzigen Limits gelten pro Tag: für Fotos, die von außerhalb der App kommen (unten), für Upload-Links und für die Agent-Registrierung. Wenn Sie hochvolumige Batches ausführen und einen garantierten Durchsatz benötigen, schreiben Sie an felix@pedra.ai.

Tägliches Upload-Limit

Jedes Bild, das von außerhalb der App gespeichert wird, zählt zu einem Tageskontingent pro Konto: 30 pro Tag im Free-Tarif, 500 pro Tag in bezahlten Tarifen, zurückgesetzt um Mitternacht UTC. Was zählt:

  • add_images_to_property (URLs und data:-URIs)
  • 360°-Fotos, die per URL an create_virtual_tour und add_virtual_tour_scenes übergeben werden
  • Über einen Upload-Link hochgeladene Dateien und in ChatGPT angehängte Fotos, die einer Immobilie hinzugefügt werden

Fotos, die Sie per imageUrl bearbeiten, und Fotos, die in der Pedra-App hochgeladen werden, zählen nicht. Über dem Limit liefert der Aufruf 429 mit code: "upload_limit" und wird als Ganzes abgelehnt — es wird nichts gespeichert. Einträge, die für sich scheitern (eine URL, die nicht lädt, ein Foto, das kein 360°-Foto ist), zählen nicht. Mehr Spielraum in einem bezahlten Tarif? Schreiben Sie an 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"
}

Zwei verwandte Tageslimits: upload_link_limit — 5 Upload-Links pro Tag im Free-Tarif, 50 in bezahlten Tarifen (jeder Link gilt 24 Stunden, also wiederverwenden); und rate_limited — Anfragen zur Agent-Registrierung pro E-Mail-Adresse und pro IP.

Timeouts

  • Bild-Abruf: Pedra gibt nach 20 Sekunden auf, die imageUrl herunterzuladen.
  • Bild-Endpunkte (enhance, furnish, empty_room, renovation usw.): typische Antwortzeit 10–30 Sekunden.
  • Video-Endpunkt: synchron — blockiert während des Video-Renderings, das mehrere Minuten dauern kann. Setzen Sie das Timeout Ihres HTTP-Clients großzügig.

Sicheres erneutes Versuchen

Alle Endpunkte sind innerhalb einer Anfrage idempotent — die gleiche Anfrage erneut zu senden, erzeugt eine neue Generierung, niemals einen beschädigten Zustand. Fehlgeschlagene Anfragen (4xx/5xx) verbrauchen in den meisten Pfaden keine Credits; der Credit-Abzug erfolgt innerhalb der Meteor-Methode, sobald die Verarbeitung beginnt.

Brauchen Sie Hilfe?

Senden Sie eine E-Mail an felix@pedra.ai mit dem fehlgeschlagenen Request-Body und der Antwort. Wir antworten innerhalb eines Werktags. Siehe Preise für Credit- und Quoten-Optionen.