Errors

Every failure from the X3D API is a JSON object with one key. There are no error codes to map, no nested error objects, and no envelope around successful responses. This page lists the exact string each endpoint returns with each status, and says which failures are worth retrying.

The error shape#

{ "error": "Invalid material. One of: pla, petg, abs, asa, tpu" }

The message is written for a human reading a log, not for a switch statement. Match on the HTTP status, not on the text — the strings can be reworded, and two different causes sometimes share one status.

One response adds a second key. POST /api/account/api-key returns 402 with a machine-readable code when the account has no card on file. It is the only endpoint in this API that does that.

{
  "error": "Add a card on file first — API print orders are billed automatically to your saved card.",
  "code": "CARD_REQUIRED"
}

const res = await fetch("https://x3dstudios.com/api/print/orders", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.X3D_API_KEY}` },
  body: form,
});
const data = await res.json();

if (!res.ok) {
  // Every failure is { error: "<message>" }.
  throw new Error(`X3D ${res.status}: ${data.error}`);
}

if (!data.paid) {
  // 201, real order code, not paid. It will sit at PENDING_PAYMENT until
  // someone pays it, and the farm will not queue an unpaid order.
  console.warn(data.message);          // names the decline reason
  if (data.chargeOutcome === "unknown") {
    // The charge may have gone through. Read the order back before paying.
    console.warn(data.apiStatusUrl);
  } else {
    console.warn(data.paymentUrl);     // hosted page to finish paying
  }
}

Submitting an order#

The 422 analysis messages#

A 422 means the upload succeeded and the file was rejected on inspection. There are four strings you can actually receive here, and each points at a different fix.

Which check fires first#

Validation short-circuits on the first failure, so a request with three problems reports one. If you are debugging a 400 that seems to name the wrong field, this is the order the route works in.

1. The credential.
2. A readable multipart body.
3. A file part, or a modelUrl you own.
4. The five required shipping fields, then the country, then shippingSpeed.
5. material, then quality.
6. The file extension.
7. Storing the file, then analysing it.
8. The $0.50 total floor.
9. Writing the order, then charging the card.

Reading an order#

Managing your key#

The three key-management methods live on /api/account/api-key and authenticate with a signed-in browser session, not with a key. They return the same one-key envelope.

What to retry#

One status you will not see from these endpoints is 429. Nothing in the application rate-limits the print API today, so there is no backoff to implement here — see /docs/api/rate-limits for what that does and does not promise.