Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Troubleshooting
  3. Reporting an Issue

Reporting an Issue

When something is wrong and you can’t resolve it, send us this list. It is the same list every time, and it is usually enough to find your exact request in our logs on the first reply.

For routine issues, email the details to firmlydocs@firmly.ai.

If your live integration is down, contact your Firmly account team or on-call contact directly. The docs inbox is not monitored 24/7. Use the list below when you report the incident.

​​ What to send

What it is Where to find it
CF-RAY Cloudflare’s identifier for that single request. The most useful thing you can send us — it points at your exact call The CF-RAY response header, on every response from Firmly
device_id Identifies the buyer’s session, so we can follow the whole journey rather than one call The browser-session response, and inside the session JWT
Endpoint and method Which call failed e.g. POST /api/v1/domains/{domain}/cart/line-items
Timestamp (UTC) Narrows the search When you made the request
The error, quoted exactly code, error and description from the response body Copy it verbatim — don’t paraphrase. The error value is what we match on
What you expected One or two lines —

​​ Reading the CF-RAY header

Every response from Firmly carries it:


curl -i https://api.firmly.work/api/v1/browser-session \
  -X POST -H "x-firmly-app-id: YOUR_APPLICATION_ID" | grep -i '^cf-ray'


cf-ray: 881d0d5048e6752c-SEA

The part after the dash is the Cloudflare location that served the request. Send the whole value, including it.

Capture it in your own logging too — the header is on successful responses as well as failures, so logging it for every call means you already have it when something goes wrong later.

​​ An example report 


Endpoint:  POST /api/v1/domains/staging.luma.gift/cart/line-items
Time:      2026-10-13T14:22:06Z
CF-RAY:    881d0d5048e6752c-SEA
device_id: fdf5c4d6-4f21-43a8-90f1-11e202e5d782
App ID:    8b348e2d (first 8 only)


Response:
{ "code": 412, "error": "PostalCodeRequired",
  "description": "A postal code is required before line items can be modified." }


Expected: the item to be added. The cart was created moments earlier in the same session.

​​ Before you send

Two things resolve most reports without an email:

  • Look up the error value in Errors & Conventions. Every error we return is listed there with what causes it and how to recover.
  • Check Common issues for the symptom. Configuration mismatches and first-week gotchas are collected there.