Error codes and how to retry them

Every failure returns a JSON body, and every endpoint answers with the same envelope, so the codes below apply across the API rather than per endpoint. The reference pages show the success response; the failures live here. Branch on error_code where it is present, and always keep a default case that surfaces message and details.suggestion, so an unfamiliar code degrades into a readable failure instead of a crash.

Status codes

Status	Meaning
`200`	Request succeeded.
`201`	Resource created.
`204`	Request succeeded with no body.
`400`	Invalid request format, missing fields, malformed JSON, or a PSD that could not be processed.
`401`	Missing, malformed or revoked credentials.
`402`	The request cannot be paid for, or a trial account is over a trial limit. Read `error_code` to tell the cases apart.
`403`	Not available with this credential, or the account is at its stored PSD template or webhook endpoint ceiling.
`404`	Resource not found. Check `mockup_uuid`, `smart_object_uuid` or `key_id`.
`409`	Conflicts with something that already exists or is still running: an `Idempotency-Key` reused for a different upload, a font name already on the account or the font ceiling reached, or a photo mockup still being prepared.
`413`	The body is larger than the endpoint accepts. Applies to a PSD upload and to a background removal request.
`422`	Body validation failed. Fix the input before retrying.
`429`	Rate limit or concurrency limit exceeded. Read `Retry-After`.
`500`	Unexpected server error. Safe to retry with backoff.
`502`	An upstream image source returned a `5xx`. Safe to retry with backoff.

Error shapes

Most errors carry a human-readable message:

Standard error

{
  "detail": "Human-readable error message",
  "success": false
}

PSD and render failures add a machine-readable error_code and a details object with a suggestion:

Structured error

{
  "error_code": "PSD_PARSE_FAILED",
  "message": "Failed to parse PSD file",
  "detail": "Failed to parse PSD file",
  "details": {
    "reason": "Invalid or corrupted PSD/PSB header",
    "suggestion": "Re-export the PSD from Adobe Photoshop"
  },
  "success": false
}

Upload error codes

POST /api/v1/psd/upload returns these on error_code.

Code	HTTP	What to do
`PSD_DOWNLOAD_FAILED`	400	The file could not be fetched. Check that the URL is public and serving.
`PSD_PARSE_FAILED`	400	Invalid or corrupted PSD or PSB. Re-export from Photoshop.
`DIMENSION_TOO_LARGE`	400	Pixel dimensions exceed 10000 by 10000. Resize the document.
`NO_SMART_OBJECTS`	400	No visible smart object and no text layer. Make one visible or add one.
`UNSUPPORTED_FEATURE`	400	Flatten or simplify the layer that uses it.
`UNSUPPORTED_SMART_OBJECT_FORMAT`	400	A smart object holds a vector format. Rasterize the layer in Photoshop.
`LINKED_SMART_OBJECT_CONTENT_MISSING`	422	Permanent: the same file returns the same result. Run Embed Linked in Photoshop, or supply the design in the render request. Most linked smart objects render fine as placeholders and need no embedding.
`SMART_OBJECT_EXTRACTION_FAILED`	500	The smart object may be damaged. Re-export it.
`LAYER_RENDER_FAILED`	500	A layer could not be rendered. Simplify its effects.
`INTERNAL_ERROR`	500	Retry the upload.
`UPLOAD_PROCESSING`	503	The upload needs longer than the call waits and carries on. Follow the job at `details.status_url` until it finishes, or upload with `is_async`.

A successful upload can also carry advisory codes under warnings, and they never fail it. Hidden layers covers PSD_HIDDEN_SMART_OBJECTS, and PSD compatibility covers PSD_NESTED_CONTENTS_UNAVAILABLE. PSD_GRADIENT_MAP_UNSUPPORTED counts the Gradient Map layers that renders do not apply, so the layers below them render without the gradient: a map with a Noise gradient, a colour stop outside RGB, or a method other than Perceptual, Linear, Classic or Smooth. In Photoshop, switch it to a Solid gradient with RGB colour stops and one of those methods, or merge it into the layer below, then upload the PSD again.

Render error codes

Render, text layer, font, artwork and photo mockup failures use the same error_code field. Take the HTTP status from the response rather than from this table. These are the codes integrations hit most often, not an exhaustive registry.

Code	What it means and what to do
`OUTPUT_RESOLUTION_LIMIT`	The account is in trial and the output width is above the 1024 px cap: a numeric `image_size`, or the template’s own width with `"original"`. Lower `image_size`, or add a payment method to render at full width.
`OUTPUT_TOO_LARGE_FOR_WEBP`	The requested WebP output is too large to encode. Reduce `image_size`, or use PNG output.
`REUPLOAD_REQUIRED`	The mockup data is incomplete or outdated. Re-upload the PSD, then retry. Retrying the same render will keep failing.
`ASSET_UNREACHABLE`	The artwork could not be downloaded. Check that the URL is public. Safe to retry once the source is back.
`ASSET_BLOCKED`	The artwork URL cannot be used. Host the artwork somewhere publicly reachable, or send it as base64.
`ARTWORK_TOO_LARGE`	An artwork input exceeds the allowed file size. Downscale or recompress it before sending.
`NESTED_SLOT_CONFLICT`	The request gives a smart object an `asset` and also fills or hides a layer inside it. Send one or the other. Retrying the same body fails the same way.
`LAYER_NOT_FOUND`	A uuid in `hidden_layers` is not a layer of this PSD mockup, and the render answers `400`. Read the layer uuids from `GET /api/v1/psd-mockups/{uuid}/layers`, then retry.
`PRINT_AREA_NOT_FOUND`	A `print_area_uuid` does not belong to this photo mockup. Re-read the print areas from the mockup, then retry.
`MOCKUP_NAME_EXISTS`	A photo mockup with this name already exists. Pick a different name, since names are unique per account.
`FONT_NOT_FOUND`	An explicitly requested font identifier is not in your catalogue. Upload the font, or request one that is listed.
`psd_limit_reached`	The account is at its stored PSD template ceiling. Delete a template, or move to a plan with a higher limit. Stored templates keep rendering.

Rate limits and concurrency limits

Two ceilings answer 429: a request rate, and a cap on how many long operations run at once. Both report their state in response headers, and error.type says which one you hit.

Usage limits

The numbers, the headers, and both 429 bodies.

Retry strategy

Retry 429, 500, 502, 503, 504 and network errors. Do not retry 400, 401, 402, 403, 404 or 422: fix the request or the billing state first. Credits are charged only on successful requests.

Retry with backoff

async function apiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options)

    if (response.ok) return response.json()

    // A limit was hit. The server says how long to wait.
    if (response.status === 429) {
      const after = response.headers.get('Retry-After') || '60'
      await sleep(parseInt(after) * 1000)
      continue
    }

    // Server side or upstream. Back off and try again.
    if (response.status >= 500) {
      await sleep(Math.pow(2, attempt) * 1000)
      continue
    }

    // Client side. Fix the request instead of repeating it.
    const error = await response.json()
    throw new Error(
      error.detail || error.message || JSON.stringify(error),
    )
  }

  throw new Error('Max retries exceeded')
}

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms))
}

Webhooks

Let long jobs call you back instead of polling them.

Plans and limits

Every active plan’s concurrency and template ceilings.

API reference

PSD mockups

Photo mockups

Fonts

Video mockups

Background removal

Studio

Webhook endpoints

Webhook deliveries

Jobs

Account

Error codes and how to retry them

Status codes

Error shapes

Upload error codes

Render error codes

Rate limits and concurrency limits

Usage limits

Retry strategy

Webhooks

Plans and limits

​Status codes

​Error shapes

​Upload error codes

​Render error codes

​Rate limits and concurrency limits

Usage limits

​Retry strategy

Webhooks

Plans and limits

Status codes

Error shapes

Upload error codes

Render error codes

Rate limits and concurrency limits

Retry strategy