Errors - Genlook Documentation

Every error has the same shape. Switch on code. message is for humans and may change. status matches the HTTP status.

{
  "code": "PRODUCT_NOT_FOUND",
  "message": "Product 'shirt-42' not found.",
  "status": 404
}

VALIDATION_FAILED adds details, one entry per invalid field:

{
  "code": "VALIDATION_FAILED",
  "message": "Request body failed validation. See `details` for per-field errors.",
  "status": 400,
  "details": [{ "path": "products.0.images.0.source.url", "message": "Required" }]
}

Generation failures don’t come back as HTTP errors: they show up as errorCode on Generation Status (marked async below). Failed generations are refunded. Every error response carries an x-request-id header. Include it when you contact support.

Codes

Code	HTTP	Meaning	Retry
`MISSING_API_KEY`	401	No `x-api-key` header.	No
`INVALID_API_KEY`	401	Key wrong, revoked or account inactive.	No
`FORBIDDEN`	403	The resource belongs to another account.	No
`VALIDATION_FAILED`	400	Invalid body. See `details`.	No
`EXTERNAL_ID_REQUIRED`	400	`POST /products` without `externalId`.	No
`PRODUCT_IMAGES_REQUIRED`	400	New or one-shot product without an image.	No
`CUSTOMER_IMAGE_REQUIRED`	400	Try-on without `person`.	No
`FILE_REQUIRED`	400	Upload without `file`.	No
`MULTIPART_FILE_NOT_FOUND`	400	A `fileKey` has no matching file field.	No
`INVALID_IMAGE_INPUT`	400	An image has neither `url` nor `fileKey`.	No
`INVALID_IMAGE`	400	File is not a valid image.	No
`UNSUPPORTED_IMAGE_TYPE`	400	Not JPEG, PNG, WebP or HEIC.	No
`CUSTOMER_IMAGE_FETCH_FAILED`	400	`person` URL could not be downloaded.	Once, then fix the URL
`PRODUCT_IMAGE_FETCH_FAILED`	async	A product image URL could not be downloaded.	Once, then fix the URL
`MISSING_REQUIRED_CLASSIFICATION`	422 or async	The product type needs a specific image (e.g. worn on a model, `details.key` says which).	After adding the image
`FILE_TOO_LARGE`	413	An image is over 10 MB.	After resizing
`INSUFFICIENT_CREDITS`	402	Balance is 0.	After top-up
`QUOTA_EXCEEDED`	402	Account quota reached, usually temporary.	Yes, with backoff
`RATE_LIMITED`	429	Too many requests.	Yes, honor `Retry-After`
`PRODUCT_NOT_FOUND`	404	Product expired or never created.	Resend the product inline
`GENERATION_NOT_FOUND`	404	Wrong generation ID.	No
`ACCOUNT_NOT_FOUND`	404	Account lookup failed (rare).	No
`ROUTE_NOT_FOUND`	404	Unknown path. Body may not follow the error shape.	No
`RESERVED_EXTERNAL_ID`	409	`externalId` starts with `_anon_`.	No
`INTERNAL_ERROR`	500	Unexpected server error.	Yes, up to 3 times
`GENERATION_FAILED`	async	The generation failed.	Yes, up to 3 times
`GENERATION_TIMEOUT`	async	The generation didn’t finish in time.	Yes

Contact support@genlook.app with the generation ID if an error persists.

Example

const r = await fetch("https://api.genlook.app/tryon/v1/try-on", { method: "POST", headers, body });
if (!r.ok) {
  const err = await r.json();
  switch (err.code) {
    case "PRODUCT_NOT_FOUND":    /* resend the product inline */ break;
    case "INSUFFICIENT_CREDITS": /* ask the user to top up */ break;
    case "VALIDATION_FAILED":    console.error(err.details); break;
    default:                     throw new Error(`${err.code}: ${err.message}`);
  }
}

The SDK throws a typed class per code instead.