Errors

The Decal API returns errors as a flat JSON object. Knowing the shape and how to read it will help you build robust integrations and get faster support when something goes wrong.

Error response shape

{
  "code": "ORDER_NOT_FOUND",
  "message": "Order not found.",
  "errorId": "err_abc123",
  "timestamp": "2026-04-15T10:00:00.000Z"
}

HTTP status codes

Decal API endpoints never return 5xx for client-side problems. Anything caused by your request returns a 4xx with a specific code.

Validation errors

When a request fails schema and data validation, the response uses the code VALIDATION_ERROR and includes the list of failed checks under details.errors. Each entry is an issue describing the field path that failed and why.

{
  "code": "VALIDATION_ERROR",
  "message": "One or more fields are invalid",
  "errorId": "err_abc123",
  "timestamp": "2026-04-15T10:00:00.000Z",
  "details": {
    "errors": [
      {
        "code": "invalid_type",
        "expected": "number",
        "received": "undefined",
        "path": ["items", 0, "unitPrice"],
        "message": "Required"
      }
    ]
  }
}

The path array points at the offending field in the request body. Use it to surface field-level errors back to your own UI when proxying through Decal.

Error codes

Error codes follow the format RESOURCE_ACTION_RESULT (e.g. ORDER_CREATE_FAILED). The set of codes an endpoint can return is documented on each endpoint reference page:

• Orders API errors
• Checkout Sessions API errors

Using errorId for support

Every error response includes a unique errorId. When contacting Decal support about an unexpected error, include this ID — it lets us look up the exact request, including request context, in our logs.

We recommend logging the errorId along with your own request context whenever your integration catches a non-2xx response:

const response = await fetch("https://api.usedecal.com/v0/orders", {
  /* ... */
});

if (!response.ok) {
  const error = await response.json();
  logger.error(
    {
      decalErrorId: error.errorId,
      decalErrorCode: error.code,
      myRequestId,
      orderId,
    },
    "Decal API error",
  );
}