Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

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, 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.

HTTP statuses

StatusMeaning
400The request is invalid: bad parameters, body, or headers
401No credential, or an invalid one
402A plan quota or paid-plan feature: not a rate limit, waiting won't help
403The credential is valid but not allowed to do this (key type, origin, unverified email, suspension)
404Not found in the authenticated project
409Conflicts with current state (an export or upload already in progress, a limit on keys or webhooks)
410Gone: an expired export archive, or an idempotent result whose asset was deleted
413The file is larger than allowed
422Understood but refused: idempotency key reuse, unsupported media, rejected prompts
429Rate limited; see Rate limits
5xxA PixelVault or upstream failure

When to retry

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

RetryWhat to do
Retry with backoffTransient. 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 on uploads so a retry can't store a duplicate.
Honour Retry-AfterWait the number of seconds in the Retry-After header, then retry. Don't retry in a tight loop.
Fix the requestRetrying the same request will fail the same way. Change the request (parameters, file, key, id) first.
Account actionSomeone has to act on the account: verify the email, delete media, upgrade, or wait for the monthly reset (resets_at in GET /v1/usage). Don't retry automatically.
Example
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 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.

CodeStatusWhat happenedWhat to doRetry
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
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
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
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
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
generation_forbidden 403 A publishable key was used to generate an image. Call POST /v1/images/generate with a secret key. Fix the request
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
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
invalid_credentials 401 The email and password do not match an account. Check the credentials, or reset the password. Fix the request
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
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
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
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
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
private_forbidden 403 A publishable key asked for a private upload. Use a secret key for private media, or upload publicly. Fix the request
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
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
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
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
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
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
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

Validation

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

CodeStatusWhat happenedWhat to doRetry
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
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
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
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
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
code_expired 400 The verification, password-reset or sign-in code has expired. Request a new code. Fix the request
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
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
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
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
enrichment_duration_too_long 422 The video or audio is longer than enrichment supports (10 minutes). Enrich a shorter asset. Fix the request
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
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
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
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
invalid_choice 400 The use-case survey answer is not one of the fixed choices. Send one of the listed choices. Fix the request
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
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
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
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
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
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
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
invalid_json 400 The request body is not valid JSON. Send a well-formed JSON body with Content-Type: application/json. Fix the request
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
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
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
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
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
invalid_url 201, 400 The import URL (or a redirect target) is not a valid URL. Send an absolute https:// URL. Fix the request
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
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
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
missing_url 400 A URL import was requested without a `url` string. Send a JSON body with a `url` string. Fix the request
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
no_images 400 The batch's `images` array is missing or empty. Send at least one image in `images`. Fix the request
optimization_duration_too_long 422 The video is longer than social-ready optimization supports (60 seconds). Optimize a shorter video. Fix the request
optimization_source_too_large 413 The video is larger than social-ready optimization accepts (100 MB). Optimize a smaller video. Fix the request
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
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
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
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
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
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
too_many_attempts 400 Too many wrong guesses were made for this verification or reset code. Request a new code. Fix the request
too_many_images 400 The batch contains more images than the per-batch maximum. Split the images across several batches. Fix the request
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
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
unsupported_scheme 201, 400 The import URL does not use https://. Use an https:// URL. Fix the request
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
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
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
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
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

Not found

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

CodeStatusWhat happenedWhat to doRetry
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
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
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
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
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
no_subscription 404 The billing portal was requested for an account with no billing history. Start a subscription with checkout first. Account action
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
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
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
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

Conflicts

The request clashes with the current state of a resource.

CodeStatusWhat happenedWhat to doRetry
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
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
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
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
concurrent_part_conflict 409 Concurrent requests uploaded different bytes for the same resumable part. Start a new upload. Fix the request
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
email_taken 409 An account with this email already exists. Sign in with that email instead of registering. Fix the request
export_expired 410 The export's download has expired. Start a new export. Fix the request
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
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
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
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
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
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
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
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
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
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
upload_complete 409 The resumable upload is already complete. Use the created video; delete it to remove it. Fix the request
webhook_url_exists 409 The project already has a webhook with that URL. Update the existing webhook instead of creating another. Fix the 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.

CodeStatusWhat happenedWhat to doRetry
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
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
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
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
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
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
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
model_requires_paid_plan 402 The chosen generation model is only available on paid plans. Use the default generation model, or upgrade. Account action
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
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
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
storage_limit_reached 201, 402 The upload would exceed the plan's storage allowance. Delete media to free space, or upgrade. Account action
upload_limit_reached 201, 402 The plan's monthly upload count is used up. Wait for the monthly reset, or upgrade. Account action
webhook_limit_reached 409 The project already has as many webhooks as its plan allows. Delete a webhook, or upgrade. Account action
webhooks_require_paid_plan 402 Webhooks are only available on the Starter and Pro plans. Upgrade to create webhooks. Account action

Rate limits

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

CodeStatusWhat happenedWhat to doRetry
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
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
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

Upstream failures

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

CodeStatusWhat happenedWhat to doRetry
billing_error 502 Stripe could not start checkout, open the portal or load the subscription. Retry shortly. Retry with backoff
editing_failed 502 The editing model failed or returned an unusable image (credits are refunded). Retry with backoff. Retry with backoff
editing_timeout 504 The editing model timed out (credits are refunded). Retry with backoff. Retry with backoff
editing_unavailable 503 Image editing is not available right now. Retry later. Retry with backoff
enrichment_unavailable 503 Video or audio enrichment (transcription) is temporarily unavailable. Retry later. Retry with backoff
generation_failed 502 The generation model failed or returned an unusable image (credits are refunded). Retry with backoff. Retry with backoff
generation_timeout 504 The generation model timed out (credits are refunded). Retry with backoff. Retry with backoff
generation_unavailable 503 Image generation is not available right now. Retry later (honour Retry-After when present). Retry with backoff
optimization_unavailable 503 Social-ready video optimization is temporarily unavailable. Retry later. Retry with backoff
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
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
poster_unavailable 503 Video poster generation is temporarily unavailable. Retry later. Retry with backoff
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

Server errors

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

CodeStatusWhat happenedWhat to doRetry
audio_policy_pending 503 Audio hosting is not enabled yet because its maximum file size has not been configured. Retry later. Retry with backoff
billing_unavailable 503 Billing or the requested paid plan is not configured. Retry later. Retry with backoff
server_error 500 An unexpected error occurred on PixelVault's side. Retry with backoff; report it if it persists. Retry with backoff
temporarily_unavailable 503 A key could not be generated right now; nothing was written. Retry. Retry with backoff
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

Next steps