Errors & Conventions

This is the canonical reference for how Firmly returns errors and how your code should respond to them.

​​ Error response shape

Every error response uses the same envelope (the REST envelope — used by all endpoints except the UCP protocol bridge):

{
  "code": 409,
  "error": "NotEnoughStockError",
  "description": "The amount of the required item is not available in stock."
}

The description field is safe to log verbatim. Don’t show it raw to buyers — it can leak technical detail. Map to your own user-facing messaging.

​​ Catalog by category

​​ Authentication

​​ Routing & resource lookup

​​ Validation

​​ Inventory & merchant state

​​ Server

​​ Place-order specific (on cc.firmly.work)

​​ Additional errors by name

Every error the endpoint pages document, beyond the grouped tables above. The last column links to the page carrying the full cause-and-recovery detail for that call.

​​ Rate limits

A 429 response means you’ve exceeded your tenant’s rate limit. Honor the Retry-After header.

For the full pattern, recommended retry logic, and how to design high-volume integrations, see Rate limits.

​​ Pagination

Firmly uses two pagination styles depending on the endpoint. Discovery search returns a cursor in next_page when more results are available — pass it on the next request to walk forward. Catalog listing (Get All Products) uses page-number pagination instead: pass page and size, and read page / size / totalPages from the response’s metadata object (with products as a sibling of metadata).

For both patterns, page-size guidance, and cursor-expiry handling, see Pagination.

​​ Idempotency

Pass an Idempotency-Key header (a UUID your code generates) on a mutation request routed through the UCP protocol bridge (see the scope note below). Reuse the same key when retrying the same attempt; generate a fresh key only for a new attempt.

On a UCP-routed mutation, the first time the server sees a given key the mutation runs normally and the response is cached for 24 hours; a retry with the same key returns the cached response, so the underlying operation runs at most once. This applies to the UCP bridge only — core REST endpoints do not deduplicate on the header (see the scope note below).

POST /api/v1/ucp/rest/domain/{domain}/checkout-sessions/{session_id}/complete
Idempotency-Key: 7c2a8b1e-4f3d-4a1c-9e6b-2d0a8e7c1b3a

If the same key is reused with a different request body, the UCP bridge rejects the request with the UCP envelope code idempotency_conflict (“idempotency key reused with different parameters”). Either retry with the original body, or generate a new key for the new attempt. (This is UCP-bridge-only — there is no equivalent REST error, since core REST endpoints don’t deduplicate on the header.)

For the full key format and the conflict-detection fingerprint, see Idempotency.

​​ Recovery patterns for common failure modes

​​ Stock changed between discovery and place-order

The classic race: showed the user a product, they confirmed, someone else bought it before you got to place-order.

add-line-item    → OK
set-shipping     → OK
place-order      → 409 NotEnoughStockError

Recovery: re-fetch the product, surface the change (“only 1 left — want to proceed with 1 instead of 2?”), update the cart with the new quantity, then retry place-order.

​​ Payment declined

place-order      → 422 CreditCardDeclined

Recovery: do not silently retry the same card. Tell the user the card was declined (without showing the issuer’s reason verbatim — that can leak signals about valid card numbers). Offer a different payment method. (A 412 CheckoutError is a distinct, merchant-side checkout failure — promo re-evaluation or a total mismatch — not a card decline.)

​​ Validation error with field path

set-shipping-info → 400 InvalidInputBody
                    "At path: phone — Expected a string with a length between 10 and 13"

The description includes the failing field. Map it to a conversational ask (“what’s the phone number with country code?”) rather than echoing the raw error.

​​ Merchant adapter down

An adapter is Firmly’s connector for a merchant’s commerce platform (see the glossary). Each implements only what its platform supports — hence OperationNotSupported / NotImplemented on some merchants.

add-line-item    → 503 StoreUnavailable

Recovery: retry with exponential backoff. If persistent for >30 seconds, surface to user.

​​ get-availability not supported

get-availability → 501 NotImplemented

Some merchants (V1 adapters) don’t implement this endpoint. This doesn’t block checkout: get-availability only returns delivery dates, time slots, and pickup locations — never shipping methods. Shipping methods always come from cart.shipments[].shipping_method_options, populated inline after set-shipping-info. Treat a 501 as “no scheduled-delivery/pickup detail for this merchant” and proceed. See Shipping & Fulfillment.

​​ UCP envelope (UCP protocol layer only)

Consumers of the UCP protocol bridge see a different envelope. Documented here for completeness — most direct REST integrations never see it.

{
  "messages": [
    {
      "type": "error",
      "code": "insufficient_stock",
      "content": "Product 'Example Item' has only 2 in stock",
      "severity": "requires_buyer_input",
      "field": "items[0].quantity"
    }
  ],
  "ucp": { "version": "1.0" }
}

​​ Severity → agent behavior (UCP only)

​​ UCP code catalog

​​ Quick reference

​​ Need help?