Error Handling

The Pictify API uses standard HTTP status codes with plain JSON error bodies.

Error Response Format

Errors carry a human-readable message under one of two keys — message (most endpoints) or error (some rendering endpoints). Handle both:

{
  "message": "Template not found"
}

{
  "error": "templateUid is required"
}

Two extensions appear on specific endpoints:

code — a stable machine-readable slug on newer endpoints (video, workflows, stock): quota_exceeded, template_limit_reached, ai_unavailable, stock_unavailable, invalid_variable, preview_not_supported.

{
  "message": "You've used all your renders for this month. Upgrade your plan to unlock more, or hang tight until next month!",
  "code": "quota_exceeded"
}

errors — an array of strings when a template fails to compile (video code templates return 422 with every compiler error at once):

{
  "errors": [
    "UserScene.tsx: 'styled-components' is not an allowed import",
    "schema must export a default for every field"
  ]
}

// A tolerant reader that covers every Pictify error shape
const readError = (body) =>
  body?.message || body?.error || (body?.errors || []).join('; ') || 'Request failed';

HTTP Status Codes

Code	Meaning	What to do
`200 OK`	Request succeeded	—
`400 Bad Request`	Invalid parameters	Fix the request; the message names the field
`401 Unauthorized`	Missing or invalid API key	Check the `Authorization: Bearer` header
`402 Payment Required`	Credits exhausted (video/workflow endpoints), or a plan limit reached	Upgrade, or wait for the monthly reset
`404 Not Found`	Resource doesn’t exist or belongs to another team	Check the uid
`422 Unprocessable Entity`	Semantically invalid (bad variables, compile errors)	Read `message` or `errors[]`
`429 Too Many Requests`	`code: "quota_exceeded"` → monthly credits exhausted (image/GIF/template/batch endpoints); otherwise a per-minute rate limit	Quota: upgrade or wait for the reset. Rate: back off and retry
`500 Internal Server Error`	Unexpected server error	Retry once, then contact support
`501 Not Implemented`	Feature not configured on this server	The message explains what’s missing
`502 Bad Gateway`	An upstream service (AI, transcription) failed	Retry

Authentication failures return 401 with the body { "message": "Invalid Request" } — deliberately unspecific, so a probing caller cannot distinguish a revoked key from a malformed one.

Common Errors

Out of credits

Every render — image, GIF, PDF page, video — consumes monthly credits. When they run out, the video and workflow endpoints return 402; the image, GIF, HTML-template and batch endpoints return 429 — both with the same body:

{
  "message": "You've used all your renders for this month. Upgrade your plan to unlock more, or hang tight until next month!",
  "code": "quota_exceeded"
}

Template not found (404)

Templates are scoped to your team. A valid uid owned by a different team returns 404, not 403.

Invalid variables (422)

Rendering with variables that violate the template’s declared definitions:

{
  "message": "Variable \"recipientName\" is required and was not provided.",
  "code": "invalid_variable"
}

Retries

On a 429 check code first: quota_exceeded is a monthly limit that no retry refills. Rate-limit 429s (public rendering, previews) send standard x-ratelimit-* and retry-after headers — honour those. On 5xx, one immediate retry is safe — all generation endpoints are idempotent from your side (a failed request bills nothing).

Overview

Images

GIFs

PDFs

Templates

Batch

URL Rendering

Video

Workflows

Webhooks

Bindings

Error Handling

Error Handling

Error Response Format

HTTP Status Codes

Common Errors

Out of credits

Template not found (404)

Invalid variables (422)

Retries

​Error Handling

​Error Response Format

​HTTP Status Codes

​Common Errors

​Out of credits

​Template not found (404)

​Invalid variables (422)

​Retries

Error Handling

Error Response Format

HTTP Status Codes

Common Errors

Out of credits

Template not found (404)

Invalid variables (422)

Retries