> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> API error codes and troubleshooting

# 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:

```json theme={null}
{
  "message": "Template not found"
}
```

```json theme={null}
{
  "error": "templateUid is required"
}
```

Two extensions appear on specific endpoints:

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

```json theme={null}
{
  "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):

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

```javascript theme={null}
// 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 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 |

<Note>
  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.
</Note>

## Common Errors

### Out of credits

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.