Errors

Every error from the API is RFC 9457 problem details, with Content-Type: application/problem+json:

{
  "type": "https://perfectvector.com/docs/api/errors#insufficient_credits",
  "title": "Not enough API credits",
  "status": 402,
  "detail": "This request needs 1 API credit. Available: 0.",
  "code": "insufficient_credits",
  "request_id": "req_4Tq8WmX2r9LcB0vZs7KpY1",
  "credits_required": 1,
  "credits_available": 0
}

Errors are never charged. A 403 or 429 whose body is not problem details comes from our network edge, not from the API: see Limits.

A failed conversion is not an error: it answers 201 or 200 with "status": "failed". See Failed conversions below.

All codes

Codes

invalid_request

400. The request has a missing, unknown or invalid part: a form field other than image and options, no image or more than one, options that is not valid JSON or asks for something v1 does not offer, a malformed Idempotency-Key, or a body that cannot be parsed. errors lists each problem as {"location", "message"}, for example {"location": "header.Idempotency-Key", …}. The API never echoes back what you sent.

invalid_api_key

401. The key is missing, malformed, unknown or revoked, or its account was deleted. A key sent anywhere but the Authorization header is ignored. The answer carries WWW-Authenticate: Bearer realm="PerfectVector API". See Authentication.

insufficient_credits

402. Your available API credits are lower than the request's price. Nothing started. credits_required and credits_available give the numbers, and X-Credits-Remaining the balance. Buy credits (Credits), then retry with the same Idempotency-Key.

account_suspended

403. We suspended the account's API access, for example for abuse or a payment problem. A new key does not help. Contact contact@perfectvector.com. A suspension, and the lifting of one, takes effect on the API within 30 seconds, so a request made right after we lift it can still get this error: wait 30 seconds and send it again.

access_not_granted

403. The key is valid, but the API is not open to this account yet. Do not rotate the key. Contact contact@perfectvector.com.

not_found

404. No such path, or no conversion with this ID for this key's account and mode (a malformed ID answers the same way), or no result with this index. A test key cannot see live conversions, and a live key cannot see test ones.

method_not_allowed

405. The path exists, but not with this HTTP method.

idempotency_conflict

409. This Idempotency-Key was used in the last 24 hours for a different request (another image or other options). Nothing was created or charged. Send a new key. See Idempotency.

conversion_in_progress

409. DELETE was called while the conversion is still running. conversion_status says queued or processing. Delete it after it has finished.

result_not_ready

409. The result cannot be downloaded: result_status says whether it is queued, processing or failed. Poll GET /v1/vectorizations/{id} until it has succeeded.

result_expired

410. The result was available for 24 hours after the conversion completed, and that time has passed, or the conversion was deleted. The SVG cannot be recovered; convert the image again if you need it. See Results.

file_too_large

413. The image is larger than 5 MiB, or the whole request is larger than 5 MiB plus 16 KiB. max_bytes is 5242880. A declared request size over the limit is refused before the key is checked.

unsupported_media_type

415. The image is not PNG, JPEG or WebP (checked from its content), or the request is not multipart/form-data. supported lists image/png, image/jpeg and image/webp.

invalid_image

422. The image cannot be read: it is empty, damaged, cut off or animated, or a side is smaller than 100 or larger than 4096 pixels. min_dimension and max_dimension give the limits.

rate_limited

429. You reached a per-minute limit (creates, POST attempts or other requests), or sent too many invalid keys from one IP address. Wait the Retry-After seconds (also in retry_after). See Limits.

too_many_in_flight

429. Your account already has as many live conversions running as its limit allows (1 by default). in_flight and max_in_flight give the numbers; Retry-After is 5. Send the next image when the running one has finished. (When your available credits cover only the running conversion, you get 402 insufficient_credits instead.)

internal_error

500. Something went wrong on our side. Retry with the same Idempotency-Key. If it keeps happening, contact us with the request_id.

service_busy

503. The API is at capacity or a part of it is briefly unavailable. Wait the Retry-After seconds (also in retry_after) and retry with the same Idempotency-Key.

api_paused

503. We paused live conversions, for example during maintenance. Retry-After is 60. Test keys keep working.

Failed conversions

When a conversion fails, the request still succeeds as HTTP (201 from POST, 200 from GET). The object has "status": "failed", the result has an error, and credits_charged is 0.

Retry a failed conversion with a new key: the same key returns the same failed conversion.