<!-- Markdown twin of https://pixelvault.dev/docs/errors/ -->

# Errors

PixelVault uses conventional HTTP status codes and returns every error in the same envelope: an `error` object with a stable, machine-readable `code` and a human-readable `message`. Successful responses use a top-level `data` object instead.

```
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used with different video inputs."
  }
}
```

Branch on `error.code`, never on the message text, which can change. Some errors add fields next to `code` (for example `upload_id` on `idempotency_in_progress`, `job_id` on `export_in_progress`). In a [batch upload](/docs/guides/upload-images/#batch), each failed item carries its own code and the request as a whole still succeeds. Browser responses for missing or forbidden CDN assets come from `img.pixelvault.dev` as plain `403`/`404` responses, not this envelope.

Background jobs (AI descriptions, video optimization and enrichment, audio transcription, exports) report failures on the resource you poll, not as HTTP errors; their codes are listed under [Async jobs](/docs/async-jobs/#failure-codes).

## HTTP statuses

Status

Meaning

400

The request is invalid: bad parameters, body, or headers

401

No credential, or an invalid one

402

A plan quota or paid-plan feature: not a rate limit, waiting won't help

403

The credential is valid but not allowed to do this (key type, origin, unverified email, suspension)

404

Not found in the authenticated project

409

Conflicts with current state (an export or upload already in progress, a limit on keys or webhooks)

410

Gone: an expired export archive, or an idempotent result whose asset was deleted

413

The file is larger than allowed

422

Understood but refused: idempotency key reuse, unsupported media, rejected prompts

429

Rate limited; see [Rate limits](/docs/limits/)

5xx

A PixelVault or upstream failure

## When to retry

Every code in the table below has a **retry** value telling you what to do:

Retry

What to do

Retry with backoff

Transient. Retry the same request with exponential backoff and jitter (for example 0.5 s, 1 s, 2 s, … capped at 30 s). Send an [`Idempotency-Key`](/docs/idempotency/) on uploads so a retry can't store a duplicate.

Honour Retry-After

Wait the number of seconds in the `Retry-After` header, then retry. Don't retry in a tight loop.

Fix the request

Retrying the same request will fail the same way. Change the request (parameters, file, key, id) first.

Account action

Someone has to act on the account: verify the email, delete media, upgrade, or wait for the monthly reset (`resets_at` in [`GET /v1/usage`](/docs/limits/#usage)). Don't retry automatically.

Example

Node.jsPython

```
const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);

async function call(url, init, attempts = 5) {
  for (let i = 0; ; i++) {
    const res = await fetch(url, init);
    if (res.ok) return (await res.json()).data;

    const { error } = await res.json().catch(() => ({ error: { code: "unknown" } }));
    if (!RETRYABLE.has(res.status) || i === attempts - 1) {
      throw Object.assign(new Error(error.message ?? res.statusText), { code: error.code, status: res.status });
    }
    const retryAfter = Number(res.headers.get("Retry-After"));
    const delay = retryAfter > 0 ? retryAfter * 1000 : Math.min(30_000, 500 * 2 ** i) * (0.5 + Math.random());
    await new Promise((r) => setTimeout(r, delay));
  }
}

const images = await call("https://api.pixelvault.dev/v1/images", {
  headers: { Authorization: `Bearer ${process.env.PIXELVAULT_API_KEY}` },
});
```

The [SDKs](/docs/sdks/) include retry handling for transient failures.

## Error codes

Link to any code as `/docs/errors/#<code>`.

### Authentication & permissions

The credential is missing, invalid, or not allowed to do this.

Code

Status

What happened

What to do

Retry

[`account_suspended`](#account_suspended)

403

The account behind this key or session has been suspended by PixelVault, so every authenticated request is refused.

Contact support; retrying will not succeed while the suspension stands.

[Account action](#retry-account_action)

[`describe_forbidden`](#describe_forbidden)

403

A publishable key was used to request an AI description of an image.

Call POST /v1/images/{id}/describe with a secret key (pv\_live\_ or pv\_test\_).

[Fix the request](#retry-fix_request)

[`editing_forbidden`](#editing_forbidden)

403

A publishable key was used to edit an image with a model.

Call POST /v1/images/{id}/edit with a secret key or a dashboard session.

[Fix the request](#retry-fix_request)

[`email_not_verified`](#email_not_verified)

403

Checkout was requested for an account whose email address is not verified.

Verify the account's email, then start checkout again.

[Account action](#retry-account_action)

[`email_verification_required`](#email_verification_required)

403

The account's email is not verified, which keyed image uploads, video and audio uploads, claims, image generation and image editing require.

Verify the email with the emailed code (POST /v1/auth/verify-email), then retry.

[Account action](#retry-account_action)

[`generation_forbidden`](#generation_forbidden)

403

A publishable key was used to generate an image.

Call POST /v1/images/generate with a secret key.

[Fix the request](#retry-fix_request)

[`human_check_failed`](#human_check_failed)

403

The Turnstile human check on the anonymous playground generator failed.

Reload the page to get a fresh Turnstile token and submit again.

[Fix the request](#retry-fix_request)

[`invalid_api_key`](#invalid_api_key)

401

The Authorization header is not a Bearer token, the key has an unknown prefix, or no such key exists (for example, it was revoked).

Send \`Authorization: Bearer <key>\` with a current pv\_live\_, pv\_test\_ or pv\_pub\_ key.

[Fix the request](#retry-fix_request)

[`invalid_credentials`](#invalid_credentials)

401

The email and password do not match an account.

Check the credentials, or reset the password.

[Fix the request](#retry-fix_request)

[`missing_api_key`](#missing_api_key)

401

The endpoint needs an API key and the request had no Bearer token (URL import on POST /v1/images also needs one).

Send \`Authorization: Bearer <key>\`; keyless uploads only accept a multipart file.

[Fix the request](#retry-fix_request)

[`missing_credentials`](#missing_credentials)

401

An export was requested without a Bearer token.

Send a secret API key or a dashboard session token as \`Authorization: Bearer <token>\`.

[Fix the request](#retry-fix_request)

[`no_allowed_origins`](#no_allowed_origins)

403

The publishable key has no allowed origins configured, so it cannot upload from anywhere.

Add the site's origin to the key under Publishable keys in the dashboard.

[Account action](#retry-account_action)

[`origin_not_allowed`](#origin_not_allowed)

403

The request's Origin is not on the publishable key's allowlist.

Add the exact origin (scheme, host and port) to the key's allowed origins in the dashboard.

[Account action](#retry-account_action)

[`origin_required`](#origin_required)

403

A publishable-key upload arrived without an Origin header, which browsers always send.

Upload from the browser, or use a secret key for server-side calls.

[Fix the request](#retry-fix_request)

[`private_forbidden`](#private_forbidden)

403

A publishable key asked for a private upload.

Use a secret key for private media, or upload publicly.

[Fix the request](#retry-fix_request)

[`project_management_forbidden`](#project_management_forbidden)

403

A publishable key was used to list, create, rename or delete projects.

Use a secret key or a dashboard session for /v1/projects.

[Fix the request](#retry-fix_request)

[`publishable_key_forbidden`](#publishable_key_forbidden)

403

A publishable key was used for something other than uploading an image.

Use a secret key (pv\_live\_ or pv\_test\_) for this operation.

[Fix the request](#retry-fix_request)

[`test_key_forbidden`](#test_key_forbidden)

403

A test key was used to start billing checkout or open the billing portal.

Use a live secret key (pv\_live\_) or the dashboard for billing.

[Fix the request](#retry-fix_request)

[`unauthorized`](#unauthorized)

401

The dashboard session token (or, where accepted, the secret API key) is missing, invalid or expired.

Sign in again for a fresh session token, or send a valid secret key where the endpoint accepts one.

[Fix the request](#retry-fix_request)

[`url_import_forbidden`](#url_import_forbidden)

403

A publishable key asked POST /v1/images to import from a URL.

Upload the file itself, or use a secret key for URL import.

[Fix the request](#retry-fix_request)

[`video_upload_forbidden`](#video_upload_forbidden)

403

A publishable key was used on a /v1/videos or /v1/audio endpoint.

Use a secret key or a dashboard session for video and audio.

[Fix the request](#retry-fix_request)

[`webhook_management_forbidden`](#webhook_management_forbidden)

403

A publishable key was used to manage webhooks.

Use a secret key or a dashboard session for /v1/webhooks.

[Fix the request](#retry-fix_request)

### Validation

The request is malformed or a value is out of range. Fix it before retrying.

Code

Status

What happened

What to do

Retry

[`already_verified`](#already_verified)

400

A verification code was requested for an email that is already verified.

Nothing to do: the account is verified.

[Fix the request](#retry-fix_request)

[`audio_duration_unavailable`](#audio_duration_unavailable)

422

The audio's duration is missing, under one second or invalid, so transcription cannot start.

Re-encode the audio so its duration can be read, upload it again and retry.

[Fix the request](#retry-fix_request)

[`batch_too_large`](#batch_too_large)

413

The POST /v1/images/batch request body exceeds the batch size limit.

Send fewer or smaller images per batch.

[Fix the request](#retry-fix_request)

[`blocked_host`](#blocked_host)

201, 400

The import URL points at a host PixelVault will not fetch from (private, loopback or otherwise disallowed).

Use a public HTTPS URL.

[Fix the request](#retry-fix_request)

[`checksum_mismatch`](#checksum_mismatch)

400

The uploaded bytes do not match the SHA-256 the request declared.

Recompute the SHA-256 over the exact bytes sent and upload again.

[Fix the request](#retry-fix_request)

[`code_expired`](#code_expired)

400

The verification, password-reset or sign-in code has expired.

Request a new code.

[Fix the request](#retry-fix_request)

[`collection_visibility_mismatch`](#collection_visibility_mismatch)

422

A video or audio asset was added to a collection with the other visibility (public vs private).

Use a collection with the same visibility as the asset.

[Fix the request](#retry-fix_request)

[`container_mismatch`](#container_mismatch)

400

The filename extension and the Content-Type name different audio formats.

Make the filename extension match the Content-Type.

[Fix the request](#retry-fix_request)

[`content_length_mismatch`](#content_length_mismatch)

400

The number of bytes received differs from the Content-Length header.

Send a Content-Length equal to the body size.

[Fix the request](#retry-fix_request)

[`disposable_email`](#disposable_email)

400

Registration used a disposable or temporary email domain.

Register with an address you own, or upload keyless without an account.

[Fix the request](#retry-fix_request)

[`enrichment_duration_too_long`](#enrichment_duration_too_long)

422

The video or audio is longer than enrichment supports (10 minutes).

Enrich a shorter asset.

[Fix the request](#retry-fix_request)

[`enrichment_source_too_large`](#enrichment_source_too_large)

413

The source file is larger than enrichment accepts (100 MB for video, 25 MB for audio).

Enrich a smaller file.

[Fix the request](#retry-fix_request)

[`file_too_large`](#file_too_large)

201, 413

The file exceeds the size limit for the endpoint or the account's plan (batch items report it in \`items\[\].error\`).

Upload a smaller file, or upgrade the plan for a higher per-file limit.

[Fix the request](#retry-fix_request)

[`idempotency_checksum_required`](#idempotency_checksum_required)

400

A direct or resumable video/audio upload sent an Idempotency-Key without the content SHA-256.

Send X-PixelVault-Content-SHA256 (direct) or \`sha256\` (resumable) with the Idempotency-Key.

[Fix the request](#retry-fix_request)

[`invalid_audio`](#invalid_audio)

400

The bytes are not a valid MP3, WAV, M4A or OGG stream, or the container differs from the declared format.

Upload a valid audio file whose format matches its extension and Content-Type.

[Fix the request](#retry-fix_request)

[`invalid_choice`](#invalid_choice)

400

The use-case survey answer is not one of the fixed choices.

Send one of the listed choices.

[Fix the request](#retry-fix_request)

[`invalid_claim_token`](#invalid_claim_token)

400

The claim token is malformed or its signature does not verify.

Use the claim token returned with the anonymous upload, unmodified.

[Fix the request](#retry-fix_request)

[`invalid_code`](#invalid_code)

400

The verification, password-reset or sign-in code is wrong or was already used.

Re-enter the latest code, or request a new one.

[Fix the request](#retry-fix_request)

[`invalid_collection`](#invalid_collection)

400

The batch's \`collection\` object is missing or its \`type\` is invalid.

Send \`collection.type\` (at most 32 characters).

[Fix the request](#retry-fix_request)

[`invalid_data`](#invalid_data)

201

A batch item's base64 \`data\` could not be decoded (reported in \`items\[\].error\`).

Send valid base64 for that item.

[Fix the request](#retry-fix_request)

[`invalid_expires_in`](#invalid_expires_in)

400

\`expires\_in\` for a signed URL is not an integer within the allowed range.

Send an integer number of seconds within the documented range.

[Fix the request](#retry-fix_request)

[`invalid_file`](#invalid_file)

201, 400

The bytes are not a supported file type, or a stored upload could not be verified.

Upload a supported format (check the magic bytes, not just the extension).

[Fix the request](#retry-fix_request)

[`invalid_folder`](#invalid_folder)

400

\`folder\` contains characters other than letters, digits, hyphens and underscores, or is longer than 64.

Use 1-64 characters from A-Z, a-z, 0-9, - and \_.

[Fix the request](#retry-fix_request)

[`invalid_json`](#invalid_json)

400

The request body is not valid JSON.

Send a well-formed JSON body with Content-Type: application/json.

[Fix the request](#retry-fix_request)

[`invalid_metadata`](#invalid_metadata)

201

A batch item's \`metadata\` is not a valid metadata object (reported in \`items\[\].error\`).

Send \`metadata\` as a JSON object within the metadata limits, or omit it.

[Fix the request](#retry-fix_request)

[`invalid_plan`](#invalid_plan)

400

Checkout was requested for a plan that is not a paid plan.

Send one of the plan names listed in the error message.

[Fix the request](#retry-fix_request)

[`invalid_request`](#invalid_request)

400

A preferences update sent \`marketing\_emails\` as something other than a boolean.

Send \`marketing\_emails\` as true or false.

[Fix the request](#retry-fix_request)

[`invalid_sign_expires_in`](#invalid_sign_expires_in)

400

\`sign\_expires\_in\` is not an integer within the allowed range.

Send an integer number of seconds within the documented range.

[Fix the request](#retry-fix_request)

[`invalid_upload`](#invalid_upload)

400

A resumable upload's parts are not contiguous, do not add up to the declared size, or break the part-size rules.

Upload parts 1..N with equal non-final sizes of at least 5 MiB and a total equal to the declared size.

[Fix the request](#retry-fix_request)

[`invalid_url`](#invalid_url)

201, 400

The import URL (or a redirect target) is not a valid URL.

Send an absolute https:// URL.

[Fix the request](#retry-fix_request)

[`length_required`](#length_required)

411

A raw video or audio upload has no valid Content-Length header.

Send Content-Length with the body size.

[Fix the request](#retry-fix_request)

[`missing_data`](#missing_data)

201

A batch item has neither \`data\` nor \`source\_url\` (reported in \`items\[\].error\`).

Give each item base64 \`data\` or a \`source\_url\`.

[Fix the request](#retry-fix_request)

[`missing_file`](#missing_file)

400

No file was provided: the multipart \`file\` field is missing or the body is empty.

Send the file in the multipart \`file\` field (or as the raw body where supported).

[Fix the request](#retry-fix_request)

[`missing_url`](#missing_url)

400

A URL import was requested without a \`url\` string.

Send a JSON body with a \`url\` string.

[Fix the request](#retry-fix_request)

[`multipart_required`](#multipart_required)

413

A direct video upload is larger than 100 MB.

Use the resumable (multipart) video upload endpoints for files over 100 MB.

[Fix the request](#retry-fix_request)

[`no_images`](#no_images)

400

The batch's \`images\` array is missing or empty.

Send at least one image in \`images\`.

[Fix the request](#retry-fix_request)

[`optimization_duration_too_long`](#optimization_duration_too_long)

422

The video is longer than social-ready optimization supports (60 seconds).

Optimize a shorter video.

[Fix the request](#retry-fix_request)

[`optimization_source_too_large`](#optimization_source_too_large)

413

The video is larger than social-ready optimization accepts (100 MB).

Optimize a smaller video.

[Fix the request](#retry-fix_request)

[`part_checksum_required`](#part_checksum_required)

400

An idempotent resumable upload sent a part without X-PixelVault-Part-SHA256.

Send the part's SHA-256 in X-PixelVault-Part-SHA256.

[Fix the request](#retry-fix_request)

[`payload_too_large`](#payload_too_large)

413

A PATCH body for an image, video or audio asset exceeds its size limit.

Send a smaller body (trim the metadata).

[Fix the request](#retry-fix_request)

[`project_id_required`](#project_id_required)

400

An export was requested with a dashboard token but no \`project\_id\` query parameter.

Add \`?project\_id=\` with one of the account's projects.

[Fix the request](#retry-fix_request)

[`prompt_rejected`](#prompt_rejected)

400, 422

The prompt or source image was refused by PixelVault's content screen or the model's safety filter; no credits are kept.

Change the prompt; adult content is not generated.

[Fix the request](#retry-fix_request)

[`request_too_large`](#request_too_large)

413

A direct audio upload is larger than the 100 MB Worker request limit.

Import larger audio from a URL instead.

[Fix the request](#retry-fix_request)

[`source_not_editable`](#source_not_editable)

422

The source image is not a JPEG, PNG, WebP, AVIF or GIF up to 20 MB.

Edit a supported image.

[Fix the request](#retry-fix_request)

[`too_many_attempts`](#too_many_attempts)

400

Too many wrong guesses were made for this verification or reset code.

Request a new code.

[Fix the request](#retry-fix_request)

[`too_many_images`](#too_many_images)

400

The batch contains more images than the per-batch maximum.

Split the images across several batches.

[Fix the request](#retry-fix_request)

[`unsupported_audio_codec`](#unsupported_audio_codec)

400

The audio container holds a codec PixelVault does not accept (M4A must be AAC-only, OGG must be Opus or Vorbis).

Re-encode to a supported codec.

[Fix the request](#retry-fix_request)

[`unsupported_media_type`](#unsupported_media_type)

415

The Content-Type (or the imported URL's type) is not one the endpoint accepts.

Send video/mp4 for video, MP3/WAV/M4A/OGG for audio, or application/json for URL import.

[Fix the request](#retry-fix_request)

[`unsupported_scheme`](#unsupported_scheme)

201, 400

The import URL does not use https://.

Use an https:// URL.

[Fix the request](#retry-fix_request)

[`url_length_required`](#url_length_required)

400

The video or audio import URL did not return a valid Content-Length header.

Host the file somewhere that sends Content-Length, or upload it directly.

[Fix the request](#retry-fix_request)

[`url_too_large`](#url_too_large)

201, 400, 413

The file at the import URL is larger than the size limit (400 on image import, 413 on video and audio import).

Import a smaller file, or upload it with the resumable endpoints.

[Fix the request](#retry-fix_request)

[`validation_error`](#validation_error)

400

A field, header or query parameter is missing or invalid; the message names it.

Correct the field the message names and resend.

[Fix the request](#retry-fix_request)

[`video_duration_unavailable`](#video_duration_unavailable)

422

The MP4's duration could not be read or is invalid, so optimization or enrichment cannot start.

Re-encode as an H.264/AAC MP4 with fast start, upload it again and retry.

[Fix the request](#retry-fix_request)

[`video_metadata_unavailable`](#video_metadata_unavailable)

422

The MP4's metadata could not be read, so analysis, optimization or enrichment cannot complete.

Re-encode as an H.264/AAC MP4 with fast start, upload it again and retry.

[Fix the request](#retry-fix_request)

### Not found

The resource doesn't exist in the authenticated project, or was deleted.

Code

Status

What happened

What to do

Retry

[`account_not_found`](#account_not_found)

404

The account behind this key or dashboard session no longer exists (for example, it was deleted while the session was still valid).

Sign in again, or use a key from an existing account.

[Account action](#retry-account_action)

[`audio_not_found`](#audio_not_found)

404

No audio asset with that id exists in the caller's project.

Check the id (aud\_...) and that the key belongs to the same project.

[Fix the request](#retry-fix_request)

[`collection_not_found`](#collection_not_found)

404

No collection with that id exists in the caller's project.

Check the collection id, or create the collection first.

[Fix the request](#retry-fix_request)

[`export_job_not_found`](#export_job_not_found)

404

No export job with that id exists for the caller's project.

Use the id returned by POST /v1/export.

[Fix the request](#retry-fix_request)

[`image_not_found`](#image_not_found)

404

No image with that id exists in the caller's project.

Check the id (img\_...) and that the key belongs to the same project.

[Fix the request](#retry-fix_request)

[`no_subscription`](#no_subscription)

404

The billing portal was requested for an account with no billing history.

Start a subscription with checkout first.

[Account action](#retry-account_action)

[`not_found`](#not_found)

404

The endpoint does not exist, or the account, project, key or webhook it names was not found.

Check the method, path and id.

[Fix the request](#retry-fix_request)

[`project_not_found`](#project_not_found)

404

The requested project (a \`project\_id\`, the \`X-PixelVault-Project-Id\` header or a /v1/projects/{id} path) does not belong to the signed-in account, or the account has no project.

Use one of the account's project ids (GET /v1/projects lists them), or omit it where it defaults.

[Fix the request](#retry-fix_request)

[`upload_not_found`](#upload_not_found)

404

No resumable video upload with that id exists in the caller's project.

Use the upload id returned when the upload was created.

[Fix the request](#retry-fix_request)

[`video_not_found`](#video_not_found)

404

No video with that id exists in the caller's project.

Check the id (vid\_...) and that the key belongs to the same project.

[Fix the request](#retry-fix_request)

### Conflicts

The request clashes with the current state of a resource.

Code

Status

What happened

What to do

Retry

[`already_subscribed`](#already_subscribed)

409

Checkout was requested by an account that already has a paid subscription.

Change or cancel the plan in the billing portal instead.

[Account action](#retry-account_action)

[`cannot_delete_current_project`](#cannot_delete_current_project)

409

A key tried to delete the project it belongs to.

Delete the project with a key from another project of the account, or from the dashboard.

[Fix the request](#retry-fix_request)

[`cannot_revoke_current_key`](#cannot_revoke_current_key)

409

A key tried to revoke itself.

Create a new key, switch to it, then revoke the old key with the new one.

[Fix the request](#retry-fix_request)

[`claim_expired`](#claim_expired)

410

The anonymous upload behind the claim token has expired and can no longer be saved.

Upload the file again.

[Fix the request](#retry-fix_request)

[`concurrent_part_conflict`](#concurrent_part_conflict)

409

Concurrent requests uploaded different bytes for the same resumable part.

Start a new upload.

[Fix the request](#retry-fix_request)

[`conflict`](#conflict)

409

The key to revoke was already revoked, or the calling key was revoked at the same moment.

List the keys and retry with a key that still exists.

[Fix the request](#retry-fix_request)

[`email_taken`](#email_taken)

409

An account with this email already exists.

Sign in with that email instead of registering.

[Fix the request](#retry-fix_request)

[`export_expired`](#export_expired)

410

The export's download has expired.

Start a new export.

[Fix the request](#retry-fix_request)

[`export_in_progress`](#export_in_progress)

409

An export for this project is already running.

Poll the running export until it finishes before starting another.

[Retry with backoff](#retry-backoff)

[`export_not_ready`](#export_not_ready)

409

The export's download was requested before the export completed.

Poll GET /v1/export-jobs/{id} until it is complete, then download.

[Retry with backoff](#retry-backoff)

[`idempotency_in_progress`](#idempotency_in_progress)

409

A video or audio upload with this Idempotency-Key is still in progress.

Wait and retry with the same key and inputs to get the finished result.

[Retry with backoff](#retry-backoff)

[`idempotency_key_reuse`](#idempotency_key_reuse)

422

The Idempotency-Key was already used with different inputs (images, videos and audio).

Use a new Idempotency-Key for a different request.

[Fix the request](#retry-fix_request)

[`idempotency_result_deleted`](#idempotency_result_deleted)

410

The asset created under this Idempotency-Key has since been deleted.

Use a new Idempotency-Key to upload again.

[Fix the request](#retry-fix_request)

[`last_key`](#last_key)

400

Revoking this key would leave the project without a secret key.

Regenerate the key to rotate it instead of revoking it.

[Fix the request](#retry-fix_request)

[`last_project`](#last_project)

409

Deleting this project would leave the account without one; every account keeps at least one project.

Create another project first if this one should go, or keep it.

[Fix the request](#retry-fix_request)

[`not_eligible`](#not_eligible)

409

The account's initial key cannot be revealed automatically.

Use Regenerate in the dashboard to get a new key.

[Fix the request](#retry-fix_request)

[`part_already_uploaded`](#part_already_uploaded)

409

That resumable part number already holds different or unverifiable bytes.

Upload the next expected part, or start a new upload.

[Fix the request](#retry-fix_request)

[`project_not_empty`](#project_not_empty)

409

The project still holds media, an active resumable upload or an export (or gained one while it was being deleted).

Delete the project's media and wait for active uploads and exports to finish, then retry the delete.

[Account action](#retry-account_action)

[`upload_complete`](#upload_complete)

409

The resumable upload is already complete.

Use the created video; delete it to remove it.

[Fix the request](#retry-fix_request)

[`webhook_url_exists`](#webhook_url_exists)

409

The project already has a webhook with that URL.

Update the existing webhook instead of creating another.

[Fix the request](#retry-fix_request)

### Plan quotas

A plan allowance is used up. Waiting for a retry won't help: delete media, wait for the monthly reset, or upgrade.

Code

Status

What happened

What to do

Retry

[`edit_credits_exhausted`](#edit_credits_exhausted)

402

The account does not have enough edit credits left this month for the chosen model.

Wait for the monthly reset, pick a cheaper model, or upgrade.

[Account action](#retry-account_action)

[`edit_model_requires_paid_plan`](#edit_model_requires_paid_plan)

402

The chosen editing model is only available on paid plans.

Use the default editing model, or upgrade.

[Account action](#retry-account_action)

[`enrichment_limit_reached`](#enrichment_limit_reached)

402

The monthly video/audio enrichment minutes are used up; the body adds \`used\_seconds\` and \`limit\_seconds\`.

Wait for the monthly reset, or upgrade.

[Account action](#retry-account_action)

[`free_capacity_reached`](#free_capacity_reached)

429

The anonymous playground generator's shared daily capacity is used up.

Sign up for monthly credits, or retry after the Retry-After interval.

[Honour Retry-After](#retry-retry_after)

[`free_limit_reached`](#free_limit_reached)

429

This IP has used its free anonymous playground generations for today.

Sign up for monthly credits, or retry after the Retry-After interval.

[Honour Retry-After](#retry-retry_after)

[`generation_credits_exhausted`](#generation_credits_exhausted)

402

The account does not have enough generation credits left this month for the chosen model.

Wait for the monthly reset, pick a cheaper model, or upgrade.

[Account action](#retry-account_action)

[`key_limit_reached`](#key_limit_reached)

409

The project already holds the maximum number of API keys (25).

Revoke an unused key, then create the new one.

[Account action](#retry-account_action)

[`model_requires_paid_plan`](#model_requires_paid_plan)

402

The chosen generation model is only available on paid plans.

Use the default generation model, or upgrade.

[Account action](#retry-account_action)

[`optimization_limit_reached`](#optimization_limit_reached)

402

The monthly social-ready optimization minutes are used up; the body adds \`used\_seconds\` and \`limit\_seconds\`.

Wait for the monthly reset, or upgrade.

[Account action](#retry-account_action)

[`private_limit_reached`](#private_limit_reached)

201, 402

The free plan's private-asset allowance is used up.

Delete private assets, upload publicly, or upgrade for unlimited private media.

[Account action](#retry-account_action)

[`project_limit_reached`](#project_limit_reached)

409

The account already owns as many projects as its plan allows.

Delete an unused project, or upgrade for more projects.

[Account action](#retry-account_action)

[`storage_limit_reached`](#storage_limit_reached)

201, 402

The upload would exceed the plan's storage allowance.

Delete media to free space, or upgrade.

[Account action](#retry-account_action)

[`upload_limit_reached`](#upload_limit_reached)

201, 402

The plan's monthly upload count is used up.

Wait for the monthly reset, or upgrade.

[Account action](#retry-account_action)

[`webhook_limit_reached`](#webhook_limit_reached)

409

The project already has as many webhooks as its plan allows.

Delete a webhook, or upgrade.

[Account action](#retry-account_action)

[`webhooks_require_paid_plan`](#webhooks_require_paid_plan)

402

Webhooks are only available on the Starter and Pro plans.

Upgrade to create webhooks.

[Account action](#retry-account_action)

### Rate limits

Too many requests in a window. Wait for Retry-After.

Code

Status

What happened

What to do

Retry

[`account_budget_exceeded`](#account_budget_exceeded)

429

Anonymous uploads and playground generation are paused while PixelVault's spend breaker is tripped (no Retry-After).

Retry later, or authenticate with an API key: keyed uploads are not paused.

[Retry with backoff](#retry-backoff)

[`rate_limit_exceeded`](#rate_limit_exceeded)

429

A per-key, per-project, per-IP or per-account rate limit, or the day's overall generation or editing capacity, was exceeded.

Wait for the number of seconds in Retry-After, then retry.

[Honour Retry-After](#retry-retry_after)

[`rate_limited`](#rate_limited)

429

A new verification or sign-in code was requested less than 60 seconds after the last one (no Retry-After).

Wait the number of seconds given in the message before asking again.

[Retry with backoff](#retry-backoff)

### Upstream failures

A remote URL, AI model, or other dependency failed. Usually transient.

Code

Status

What happened

What to do

Retry

[`billing_error`](#billing_error)

502

Stripe could not start checkout, open the portal or load the subscription.

Retry shortly.

[Retry with backoff](#retry-backoff)

[`editing_failed`](#editing_failed)

502

The editing model failed or returned an unusable image (credits are refunded).

Retry with backoff.

[Retry with backoff](#retry-backoff)

[`editing_timeout`](#editing_timeout)

504

The editing model timed out (credits are refunded).

Retry with backoff.

[Retry with backoff](#retry-backoff)

[`editing_unavailable`](#editing_unavailable)

503

Image editing is not available right now.

Retry later.

[Retry with backoff](#retry-backoff)

[`enrichment_unavailable`](#enrichment_unavailable)

503

Video or audio enrichment (transcription) is temporarily unavailable.

Retry later.

[Retry with backoff](#retry-backoff)

[`generation_failed`](#generation_failed)

502

The generation model failed or returned an unusable image (credits are refunded).

Retry with backoff.

[Retry with backoff](#retry-backoff)

[`generation_timeout`](#generation_timeout)

504

The generation model timed out (credits are refunded).

Retry with backoff.

[Retry with backoff](#retry-backoff)

[`generation_unavailable`](#generation_unavailable)

503

Image generation is not available right now.

Retry later (honour Retry-After when present).

[Retry with backoff](#retry-backoff)

[`optimization_unavailable`](#optimization_unavailable)

503

Social-ready video optimization is temporarily unavailable.

Retry later.

[Retry with backoff](#retry-backoff)

[`poster_generation_failed`](#poster_generation_failed)

422

POST /v1/videos/{id}/poster could not extract or store a frame (source unavailable, frame extraction failed, or the storage limit was reached).

Retry later; if the message reports a storage limit, free space or upgrade first.

[Retry with backoff](#retry-backoff)

[`poster_too_large`](#poster_too_large)

422

The frame extracted for the video poster was empty or larger than the poster size limit.

Re-encode the video as an H.264 MP4 and retry poster generation.

[Fix the request](#retry-fix_request)

[`poster_unavailable`](#poster_unavailable)

503

Video poster generation is temporarily unavailable.

Retry later.

[Retry with backoff](#retry-backoff)

[`url_fetch_failed`](#url_fetch_failed)

201, 400

The import URL could not be fetched: a network error, timeout, bad redirect or non-2xx response.

Make sure the URL is public and returns the file, then retry.

[Fix the request](#retry-fix_request)

### Server errors

Something failed on PixelVault's side. Retry with backoff.

Code

Status

What happened

What to do

Retry

[`audio_policy_pending`](#audio_policy_pending)

503

Audio hosting is not enabled yet because its maximum file size has not been configured.

Retry later.

[Retry with backoff](#retry-backoff)

[`billing_unavailable`](#billing_unavailable)

503

Billing or the requested paid plan is not configured.

Retry later.

[Retry with backoff](#retry-backoff)

[`server_error`](#server_error)

500

An unexpected error occurred on PixelVault's side.

Retry with backoff; report it if it persists.

[Retry with backoff](#retry-backoff)

[`temporarily_unavailable`](#temporarily_unavailable)

503

A key could not be generated right now; nothing was written.

Retry.

[Retry with backoff](#retry-backoff)

[`upload_failed`](#upload_failed)

201

A batch item failed on PixelVault's side (reported in \`items\[\].error\`); it may still have been stored if only its URL could not be built.

Retry that item.

[Retry with backoff](#retry-backoff)

## Next steps

-   [Rate limits & quotas](/docs/limits/): what 429 and 402 mean for your plan.
-   [Idempotency](/docs/idempotency/): make retries safe.
-   [API reference](/docs/api/): the errors each endpoint can return.
