Errors

All error responses have the same shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-30T14:30:00.000Z"
  }
}

Always log meta.request_id — it's how support traces requests on our side.

Validation errors also list every field that failed in error.details, so you can show each problem next to its input:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "limit: Too small: expected number to be >=1; order: Invalid option: expected one of \"asc\"|\"desc\"",
    "details": [
      { "field": "limit", "message": "Too small: expected number to be >=1" },
      { "field": "order", "message": "Invalid option: expected one of \"asc\"|\"desc\"" }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-10-15T14:30:00.000Z"
  }
}

HTTP status codes

General error codes

Resource-specific 404s

Resource-specific 422s

Design edits

POST /v1/image-ads/:id/edits returns 400 VALIDATION_ERROR unless the body has exactly one of instruction or script. An edit that runs but cannot be applied is not an HTTP error: the response is 200 with data.status: "failed" and data.failure: { code, message } (for example script_error, invalid_design, no_change, out_of_scope). Nothing was applied and nothing was charged; fix the script or instruction and retry. See Edit ads with instructions or scripts.

POST /v1/image-ads no longer accepts editable (every ad is editable). Sending it returns 400 VALIDATION_ERROR.

JSON tree errors

PATCH /v1/image-ads/:id, PATCH /v1/design-templates/:id and Figma sync validate current_json_tree before any other work. Every failure is a 400 VALIDATION_ERROR with one details entry per path, for example current_json_tree.root.children[2].fills[0].color.r:

• The tree is not a valid schema-v2 document: an unknown key, a missing required field, an invalid enum, a non-finite number, duplicate node ids, or text segments that don't cover the characters.
• The tree uses the retired format (no schemaVersion): "This JSON tree uses the retired schema (version 1). Regenerate it with the current pipeline."

A font we don't ship is not an error: the text renders in Inter at the closest style and the tree keeps its fontName (see Fonts we do not ship).

Every IMAGE paint's sal.url must also be an absolute http(s) URL, or the request fails with 400 INVALID_IMAGE_URL (one details entry per paint path). Nothing is saved on any of these errors.

PATCH /v1/image-ads/:id then saves the tree and renders it in the background. A failed render does not return an error: the ad shows render_status: "failed" and render_error (IMAGE_UNAVAILABLE or RENDER_FAILED) and keeps its previous image.

Image upload errors

Async job failure codes

These appear in the resource's data.error.code field when an async resource lands in status: "failed". They are not HTTP status codes.

Common error scenarios

"I get 401 even though I just created the key"

• Key must be sent as X-API-Key, not Authorization: Bearer.
• The full key including the sal_live_ prefix.
• Check for trailing whitespace or newline (a frequent culprit for keys pasted from clipboards).

"I get 422 on POST /v1/image-ads"

The most common cause is a product/brand mismatch (PRODUCT_BRAND_MISMATCH). The product you passed doesn't belong to the brand you passed. Verify:

const r = await fetch(
  `https://api.staticadslab.com/v1/products/${product_id}`,
  { headers: { "X-API-Key": process.env.SAL_API_KEY } },
);
const { data } = await r.json();
console.log(data.brand_id === expectedBrandId);

Other 422 culprits: REFERENCE_AD_URL_INVALID, AUDIENCE_PRODUCT_MISMATCH, PRODUCT_VARIANT_NO_IMAGES.

"I keep getting 402 INSUFFICIENT_BALANCE in production"

You're likely hitting it after a series of fast successful generations. Top-ups are manual today. Until programmatic top-up exists, monitor error.code === "INSUFFICIENT_BALANCE" and surface a "Add funds" CTA to the operator. The error message includes the top-up URL.

Recommended client-side wrapper

class SalApiError extends Error {
  constructor(status, code, requestId, message) {
    super(message);
    this.status = status;
    this.code = code;
    this.requestId = requestId;
  }
}

async function salFetch(url, init = {}) {
  const r = await fetch(url, {
    ...init,
    headers: {
      "X-API-Key": process.env.SAL_API_KEY,
      "Content-Type": "application/json",
      ...(init.headers ?? {}),
    },
  });
  const body = await r.json();
  if (!r.ok) {
    throw new SalApiError(
      r.status,
      body?.error?.code ?? "UNKNOWN",
      body?.meta?.request_id ?? "unknown",
      body?.error?.message ?? r.statusText,
    );
  }
  return body;
}

Related

• Authentication
• Rate limits
• Idempotency