Reference

Errors & limits

HTTP status codes, error response shapes, credit limits, and timeout behavior across all Pedra API endpoints.

Error response shape

Failed requests return a non-200 HTTP status with a JSON body containing an error field describing what went wrong.

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

Status codes

The Pedra API uses a deliberately small set of status codes. There's no 401, no 429, no 413 — auth and quota errors return 404 and 403 respectively, and there are no server-side rate limits today.

Status
Meaning
200
Success. Image endpoints return output (array or single object — see each endpoint); the video endpoint returns videoId and a ready-to-stream videoUrl.
400
Bad request. Returned by /api/create_video for missing images array, missing imageUrl in an image, an invalid effect value, or effect: "transition" without secondImageUrl.
403
Insufficient credits. The error body explains how many credits the call required vs. how many remain. Top up at app.pedra.ai or email felix@pedra.ai.
404
{"error": "User not found"} — the API key didn't match any account. This is the response for missing, invalid, or revoked keys.
405
Method not allowed. All endpoints accept only POST.
500
Server error. Most often surfaces the underlying processing exception in the error field.

Common errors

User not found (404)

The API key didn't match any Pedra account. Verify the key matches what we issued and that it's in the JSON body as apiKey — not as an Authorization header.

Insufficient credits (403)

Each plan comes with a monthly credit allowance — see pedra.ai/pricing. Image endpoints cost 1 credit; each non-static video frame costs 5. When you run out, you'll get a 403 with the exact credit math. Top up or change plan at app.pedra.ai → Settings → Subscription and credits.

Invalid effect 'X' at index N (400)

The video endpoint validates effect against the set [zoom-in, zoom-out, transition, static]. The error message names the offending image index.

Image fetch failed (500)

Pedra couldn't download the imageUrl within 20 seconds. Causes: auth-walled URL, expired presigned URL, slow origin. For presigned S3/R2/Cloudinary URLs, send the image as a data:image base64 URI instead — Pedra will use the bytes directly.

Rate limits

There are no per-second or per-minute rate limits on the Pedra API today. Throughput is bounded by your remaining credits and the underlying processing capacity. If you're running high-volume batches and need a guaranteed throughput floor, email felix@pedra.ai.

Timeouts

  • Image fetch: Pedra gives up after 20 seconds trying to download imageUrl.
  • Image endpoints (enhance, furnish, empty_room, renovation, etc.): typical response 10–30 seconds.
  • Video endpoint: synchronous — blocks while the video renders, which can take several minutes. Set your HTTP client timeout generously.

Retrying safely

All endpoints are idempotent within a request — retrying the same body produces a new generation, never a corrupted state. Failed requests (4xx/5xx) do not consume credits in most paths; the credit deduction happens inside the Meteor method once processing starts.

Need help?

Email felix@pedra.ai with the failing request body and response. We respond within one business day. See Pricing for credit and quota options.