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, kein 429, kein 413 — Authentifizierungs- und Quota-Fehler geben 404 bzw. 403 zurück, und es gibt heute keine serverseitigen Rate-Limits.

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. Wird von /api/create_video zurückgegeben bei fehlendem images-Array, fehlendem imageUrl in einem Bild, ungültigem effect-Wert oder effect: "transition" ohne secondImageUrl.
403
Nicht genügend Credits. Der Fehler-Body 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.
500
Serverfehler. Zeigt meist die zugrundeliegende Verarbeitungsausnahme im error-Feld. Beim Video-Endpunkt auch beim internen 10-Minuten-Timeout zurückgegeben.

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)

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. Aufladen oder Tarif wechseln unter app.pedra.ai → Einstellungen → Abonnement und Credits.

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.

Video processing timeout after 10 minutes (500)

Der Video-Endpunkt blockiert bis zu 10 Minuten während des Renderings. Wenn das Rendering dieses Fenster überschreitet, gibt der Endpunkt 500 zurück. Das Video kann im Hintergrund noch fertig werden — kontaktieren Sie den Support mit dem Request-Body, um die endgültige URL zu erhalten.

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 heute keine pro-Sekunden- oder pro-Minuten-Rate-Limits in der Pedra-API. Der Durchsatz wird durch Ihre verbleibenden Credits und die zugrundeliegende Verarbeitungskapazität begrenzt. Wenn Sie hochvolumige Batches ausführen und einen garantierten Durchsatz benötigen, schreiben Sie an felix@pedra.ai.

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: blockiert bis zu 10 Minuten. Setzen Sie das Timeout Ihres HTTP-Clients auf mindestens 11 Minuten.

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.