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
| 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 |
| 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 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). Don't retry automatically. |
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.
| Code | Status | What happened | What to do | Retry |
|---|---|---|---|---|
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.
| Code | Status | What happened | What to do | Retry |
|---|---|---|---|---|
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.
| Code | Status | What happened | What to do | Retry |
|---|---|---|---|---|
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.
| Code | Status | What happened | What to do | Retry |
|---|---|---|---|---|
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.
| Code | Status | What happened | What to do | Retry |
|---|---|---|---|---|
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.
| Code | Status | What happened | What to do | Retry |
|---|---|---|---|---|
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.
| Code | Status | What happened | What to do | Retry |
|---|---|---|---|---|
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.
| Code | Status | What happened | What to do | Retry |
|---|---|---|---|---|
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
- Rate limits & quotas: what 429 and 402 mean for your plan.
- Idempotency: make retries safe.
- API reference: the errors each endpoint can return.