GUIDES

Errors and retries

Every refusal is { error: { code, message, requestId } }. Branch on code, show or log message, quote requestId if you write to us.

Answer

{
  "error": {
    "code": "insufficient_credits",
    "message": "This account has no credit left to unlock the image.",
    "requestId": "req_8Gq2Lw0fTz1kVb6s"
  }
}

When to retry

429: wait the Retry-After seconds, then send the same request.
500 and 503: wait a moment and retry with the same Idempotency-Key: it is never charged twice.
Every other 4xx: fix the request first. The same request gets the same answer.

Every code

Generated from the API's own registry, the list every answer is checked against.

Status	Code	What it means	What to do
400	`captcha_failed`	The challenge was not passed.	Complete the challenge again, then send the request.
400	`code_invalid`	The sign-in code is wrong, used or expired.	Ask for a new code.
400	`confirmation_required`	Erasing an account needs the typed confirmation in the body.	Send the exact phrase the reference shows.
400	`dimensions_too_large`	The image is wider or taller than we convert.	Send an image of at most the limit on each side.
400	`file_empty`	The file has no bytes.	Upload the file again.
400	`file_too_large`	The file is over the size limit.	Send a smaller file.
400	`format_unavailable`	This result has no file in that format.	Ask for one of the formats the conversion lists.
400	`input_hash_mismatch`	The inputHash you sent is not the hash of the stored file.	Upload the file again; the stored bytes are not the ones you meant.
400	`invalid_colors`	A color mapping names a color the result does not have, or is not a hex color.	Map only the result's own colors, as #rrggbb.
400	`invalid_country`	The country is not a two-letter ISO 3166 code.	Send a code like US or SG, or leave it out.
400	`invalid_cursor`	The page cursor is not one this list returned.	Start again from the first page, or pass the nextCursor you were given.
400	`invalid_email`	That is not an email address.	Check the address and send it again.
400	`invalid_filter`	The list filter is not one this list offers.	Use one of the filters the reference names.
400	`invalid_id`	An id in the path is not a UUID.	Use the id exactly as the API returned it.
400	`invalid_idempotency_key`	The idempotency key is too short, too long or has characters we do not take.	Send a UUID, or 8 to 200 letters, digits and . _ : ~ -
400	`invalid_input_key`	That upload does not belong to this account.	Upload the file with this account, then convert it.
400	`invalid_options`	An option is out of bounds or not offered yet.	Read the message for the bounds, or leave the option out.
400	`invalid_palette`	The palette's name or colors cannot be taken.	Give it a name and 1 to 24 distinct #rrggbb colors.
400	`invalid_request`	A field is missing, has the wrong type, or is not one this endpoint takes.	Read the message: it names the field. Fix it and send again.
400	`invalid_size`	The declared size is not a positive whole number of bytes.	Send the file's exact size in bytes.
400	`invalid_sort`	The list order is not one this list offers.	Use one of the orders the reference names.
400	`invalid_tiles`	A tile asked for a layer, level or position this result does not have.	Ask only for tiles inside the result's levels.
400	`invalid_token`	The link's token is malformed, expired or already used.	Ask for a new link.
400	`invalid_url`	We do not fetch that URL: only https on the standard port, with no user name or password, on the public internet.	Send a public https link to the image, or the image itself.
400	`invalid_verdict`	The verdict's vote, reasons or note cannot be taken.	Read the message: it names the field.
400	`layer_unavailable`	This result has no such layer.	Ask for a layer the reference names.
400	`malformed_body`	The body is missing, or is not a JSON object (or, where the endpoint takes a file, form data).	Send a JSON object with Content-Type: application/json, or multipart/form-data where the endpoint takes a file.
400	`malformed_image`	The file is not a readable image of the type it claims.	Export the image again and send that file.
400	`same_plan`	The account is already on that plan level.	Nothing to do. Pick another level to change it.
400	`unknown_pack`	There is no credit pack by that name.	Use one of the items GET /prices lists.
400	`unknown_plan`	There is no plan level by that name.	Use one of the plan items GET /prices lists.
400	`unknown_preset`	There is no preset by that name.	Use one of the presets the message lists.
400	`unknown_provider`	That is not a way to sign in here.	Use one of the methods GET /session offers.
400	`unsupported_type`	We do not convert that kind of file.	Send one of the formats the message lists.
400	`url_unreachable`	We could not fetch the image at that URL: no answer, a missing page, too slow, too many redirects, or too large.	Read the message for which. Check the link opens in a private window, or send the image itself.
401	`invalid_api_key`	The API key is unknown, revoked, past its end, or mistyped.	Copy the key again, or make a new one on the developer page.
401	`unauthenticated`	Nobody is signed in, or the session or key is not valid.	Sign in again, or send a valid key as Authorization: Bearer.
402	`insufficient_credits`	There are not enough credits for this unlock. None was spent.	Buy credits, then send the same request again.
402	`unlock_required`	This image is not unlocked yet, so its files do not download.	Unlock it (1 credit, once per image), then download.
403	`account_required`	Trying without an account does not include this.	Sign in or create an account. The conversions come with you.
403	`api_key_not_allowed`	An API key cannot do this: it manages the account, so only its signed-in owner may.	Do it on vecsnap.com, signed in.
403	`email_unverified`	The sign-in provider has not verified this email address.	Verify the address with the provider, or sign in with the email code.
403	`forbidden`	This caller may not do that.	Read the message: it says who may.
403	`plan_required`	Live API keys and live webhooks come with the Pro plan, and this account is not on Pro.	Choose Pro, or use test mode: it is free.
404	`api_key_not_found`	There is no such key in this account.	Use a key id GET /api-keys listed.
404	`no_plan`	This account has no plan to act on.	Subscribe first.
404	`not_found`	There is nothing at that id for this caller.	Check the id. Another account's objects read as not found too.
404	`original_unavailable`	This conversion's original is not shown here.	Show its redraw instead.
404	`palette_not_found`	There is no such palette in this account.	Use a palette id GET /palettes listed.
404	`variant_not_found`	There is no such recolor of this result.	Use a variant id this result listed.
404	`webhook_delivery_not_found`	There is no such webhook delivery in this account.	Use a delivery id GET /webhook-deliveries listed.
404	`webhook_endpoint_not_found`	There is no such webhook endpoint in this account.	Use an endpoint id GET /webhook-endpoints listed.
409	`account_exists`	An account already holds this email address under another spelling.	Sign in with that account.
409	`already_signed_in`	An account is already signed in here.	Sign out first to start a guest.
409	`already_subscribed`	This account already has a plan.	Change the plan instead of buying another.
409	`api_key_limit`	The account has the most keys of this mode it can keep.	Revoke a key you no longer use, then make the new one.
409	`conversion_failed`	The conversion ended without a result.	Convert the image again. Converting is free.
409	`conversion_running`	The image is still converting.	Wait for it to finish, then try again.
409	`idempotency_key_reused`	That idempotency key was used for a different request.	Make a new key for a new request.
409	`not_deleted`	The image is not in Recently deleted.	Delete it first, or leave it.
409	`not_in_test_mode`	Test mode makes the conversion and its SVG files only.	Use a live key for it, or test the conversion and its SVG files.
409	`not_ready`	The conversion is still running.	Wait for it to finish (a webhook, the events stream, or a read), then ask again.
409	`not_waiting`	Only a conversion waiting in line can be canceled.	Let a running conversion finish.
409	`original_not_kept`	The image's file is no longer kept, so it cannot be converted again.	Upload the file again.
409	`palette_limit`	The account has the most palettes it can keep.	Delete a palette, then save the new one.
409	`plan_active`	The account's plan still renews.	Cancel the plan first.
409	`plan_ending`	The plan is set to end.	Keep the plan first, then change it.
409	`plan_past_due`	The plan's last payment did not go through.	Update the payment method in the billing portal.
409	`plan_renewal_pending`	A renewal is being paid right now.	Try again in a few minutes.
409	`plan_renewing`	The plan renews in the next few minutes.	Try again after the renewal.
409	`plan_switch_waiting`	A change of plan is already waiting for the next renewal.	Wait for it, or keep the current plan.
409	`result_outdated`	This result was made before files were kept per format.	Convert the image again.
409	`too_many_active_jobs`	Your conversions running at once are at their limit.	Wait for one to finish, or send queue: true to wait in line.
409	`too_many_colors`	This result has too many colors to edit one by one.	Redraw it with fewer colors first.
409	`unlock_pending`	A conversion of this image is already unlocking it.	Wait for that conversion to finish.
409	`webhook_delivery_pending`	That delivery did not end in a failure: it was delivered, or it is still on its way.	Retry only a delivery that failed.
409	`webhook_endpoint_limit`	The account has the most webhook endpoints of this mode it can keep.	Delete an endpoint you no longer use, then add the new one.
422	`email_refused`	We do not open accounts for that email domain.	Use another address.
429	`free_capacity_reached`	Everyone's free conversions for today are used.	Come back after Retry-After (UTC midnight), or unlock with a credit.
429	`free_limit_reached`	Today's free conversions are used.	Come back after Retry-After (UTC midnight), or unlock with a credit.
429	`rate_limited`	Too many requests in a short time.	Wait the Retry-After seconds, then send it again.
500	`internal_error`	Something failed on our side.	Send it again. If it keeps failing, quote the requestId to support.
502	`code_unavailable`	The sign-in email could not be sent just now.	Try again in a minute.
502	`derive_failed`	A preview file could not be made just now.	Try again. The coarser picture still shows.
502	`sign_in_failed`	The sign-in provider did not finish the sign-in.	Start the sign-in again.
502	`sign_in_unavailable`	The sign-in provider could not be reached.	Try again in a minute.
503	`auth_unavailable`	We could not check who you are just now. You are not signed out.	Send it again in a few seconds.
503	`billing_unavailable`	Billing could not be reached just now.	Try again in a few minutes.
503	`checkout_unavailable`	Checkout is not open yet.	Try again later.
503	`purchases_unavailable`	Purchases are not open on this deployment.	Try again later.
503	`sign_out_failed`	The session could not be ended just now.	Try again.