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. For the video endpoint, also returned on the 10-minute internal timeout.

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.

Video processing timeout after 10 minutes (500)

The video endpoint blocks for up to 10 minutes while rendering. If rendering exceeds that window, the endpoint returns 500. The video may still complete in the background — email support with the request body to retrieve the final URL.

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: blocks for up to 10 minutes. Set your HTTP client timeout to at least 11 minutes.

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.