Chyby a správy

Volanie UCP v obchode na Monokaide sa môže pokaziť dvoma veľmi odlišnými spôsobmi. Buď sa požiadavka nedala spracovať vôbec — to je chyba protokolu s chybovým stavom HTTP — alebo sa spracovala a obchod má k výsledku čo povedať — to je správa v obyčajnej odpovedi 200. Táto kapitola ukazuje, ako odpovede rozlíšiť, a uvádza každý kód, ktorý API vracia, spolu s tým, čo má pri ňom urobiť váš klient.

Príklady používajú obchod https://shop.example.com a platformu, ktorej profil je na adrese https://platform.example.com/.well-known/ucp. Kedy a ako požiadavku zopakovať, podrobne opisuje kapitola Idempotencia, súbežnosť a limity.

Tri druhy odpovedí

Dva ďalšie druhy odpovedí vôbec nie sú JSON v tvare UCP:

• Vlastné stránky webového servera. Webový server pred obchodom niektoré situácie vybaví sám, skôr než požiadavku uvidí API, a odpovie HTML stránkou: obyčajné http://, telo nad 1 MiB, priveľa požiadaviek za sekundu, API nedostupné alebo príliš pomalé. Pozrite Odpovede, ktoré nie sú JSON.
• Stránka odovzdania. continue_url je stránka pre prehliadač kupujúceho. API ju podáva na doméne obchodu ako HTML. Váš klient ju nikdy volať nemusí.

Ako ich rozlíšiť

Odpoveď kontrolujte v tomto poradí:

Úspešná odpoveď ucp.status nikdy nemá: jeho absenciu čítajte ako úspech. Okrem 200 a 201 API žiadnu inú odpoveď 2xx nevracia a nikdy nepresmerováva (obyčajné http:// presmeruje na https:// webový server kódom 301; volajte rovno https://).

// Sort one UCP answer into the kinds above (Node 20+ fetch Response).
async function readUcp(res) {
  const retryAfter = Number(res.headers.get('retry-after')) || undefined;
  if (res.status === 304) return { kind: 'not_modified' };
  if (!(res.headers.get('content-type') ?? '').startsWith('application/json')) {
    // nginx's own HTML page: 413, 429, 502 or 504. Decide by the status alone.
    return { kind: 'web_server', status: res.status };
  }
  const body = await res.json();
  if (res.status >= 400) {
    return { kind: 'protocol_error', status: res.status, code: body.code,
             content: body.content, continueUrl: body.continue_url, retryAfter };
  }
  if (body.ucp?.status === 'error') {
    return { kind: 'business_error', code: body.messages[0].code,
             messages: body.messages, continueUrl: body.continue_url };
  }
  return { kind: 'resource', status: res.status, body, messages: body.messages ?? [] };
}

# Sort one UCP answer into the kinds above (a requests.Response).
def read_ucp(r):
    retry_after = r.headers.get("Retry-After")
    if r.status_code == 304:
        return {"kind": "not_modified"}
    if not r.headers.get("Content-Type", "").startswith("application/json"):
        # nginx's own HTML page: 413, 429, 502 or 504. Decide by the status alone.
        return {"kind": "web_server", "status": r.status_code}
    body = r.json()
    if r.status_code >= 400:
        return {"kind": "protocol_error", "status": r.status_code, "code": body["code"],
                "content": body["content"], "continue_url": body.get("continue_url"),
                "retry_after": int(retry_after) if retry_after else None}
    if body.get("ucp", {}).get("status") == "error":
        return {"kind": "business_error", "code": body["messages"][0]["code"],
                "messages": body["messages"], "continue_url": body.get("continue_url")}
    return {"kind": "resource", "status": r.status_code, "body": body,
            "messages": body.get("messages", [])}

Chyby protokolu

Telo a hlavičky

Chyba protokolu má presne dva alebo tri kľúče:

Každá chyba protokolu prichádza s Cache-Control: no-store. Retry-After v celých sekundách nesú tieto odpovede a žiadne iné:

{
  "code": "service_unavailable",
  "content": "Another request on this session is being processed — retry shortly"
}

Kódy chýb protokolu sú invalid_profile_url, profile_unreachable, profile_malformed, version_unsupported, invalid_request, request_too_large, not_found, idempotency_conflict, rate_limited, service_unavailable a internal_error. Kód vyjednávania capabilities_incompatible medzi nimi nie je: prichádza ako obchodná chyba s HTTP 200.

Obchod, hostiteľ a cesta

Chýbajúci košík, checkout alebo produkt nikdy nie je 404: je to obchodná chyba s HTTP 200.

Profil vašej platformy

Tieto chyby pochádzajú z hlavičky UCP-Agent a z profilu platformy, ktorý uvádza. Všetky nesú continue_url na úvodnú stránku obchodu. Každá požiadavka prechádza kontrolami v tomto poradí: hlavička, stiahnutie profilu, verzia a nakoniec vyjednávanie schopností.

{
  "code": "profile_unreachable",
  "content": "Unable to fetch the platform profile",
  "continue_url": "https://shop.example.com/"
}

Požiadavka

Polia sa kontrolujú, až keď sa relácia nájde a je otvorená. PUT neznámej, dokončenej, zrušenej alebo odovzdanej relácie dostane odpoveď tejto relácie — not_found, checkout_completed, checkout_canceled alebo handed_off — s HTTP 200, bez toho, aby sa jej polia čítali (skôr sa odmietne iba telo, ktoré nie je objektom JSON). Taká odpoveď nehovorí nič o tom, či bolo vaše telo platné.

Každé telo posielajte s Content-Type: application/json. Telo poslané ako text/plain, ako iný typ +json alebo bez Content-Type sa nečíta: vyhľadávanie v katalógu potom prebehne ako prázdne vyhľadávanie a na lookup, detail produktu aj každé vytvorenie alebo PUT košíka či checkoutu obchod odpovie 400 request must be an object. Telo vo formáte formulára (application/x-www-form-urlencoded) sa spracuje, no každá hodnota v ňom príde ako reťazec, takže číselné pole, napríklad quantity alebo pagination.limit, sa odmietne s 400 invalid_request. Nepoužívajte ho.

Idempotencia a súbežnosť

Prvé 409 má jednu zriedkavú druhú príčinu: dve kópie tej istej požiadavky sa predbiehali, prvá zlyhala a uvoľnila kľúč práve vtedy, keď ho druhá hľadala. Ak ste si istí, že obe kópie boli rovnaké, ďalší pokus s tým istým kľúčom požiadavku vykoná.

Limity a zlyhania

{
  "code": "rate_limited",
  "content": "Too many requests"
}

Všetky chyby polí

content chyby 400 invalid_request je jedna z týchto viet. <i> je index v poli, ktoré ste poslali; <field> je názov textového poľa.

Čo sa namiesto odmietnutia upraví

Niektoré hodnoty API upraví bez chyby. Porovnajte, čo ste poslali, s odpoveďou:

Obchodné chyby

Obchodná chyba je odpoveď HTTP 200, ktorej ucp.status je "error". Nevracia žiadny zdroj — žiadne id, žiadne položky — iba messages s jednou správou a continue_url:

{
  "ucp": {
    "version": "2026-04-08",
    "status": "error",
    "capabilities": {
      "dev.ucp.shopping.cart": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08"
        }
      ]
    }
  },
  "messages": [
    {
      "type": "error",
      "code": "not_found",
      "content": "Cart not found or has expired",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://shop.example.com/"
}

Každá obchodná chyba má závažnosť unrecoverable: tá istá požiadavka dostane tú istú odpoveď. Obchodná chyba pri zápise je výsledok ako každý iný, preto sa uloží s Idempotency-Key a pokus s tým istým kľúčom ju dostane znova — ak skúšate zmenenú požiadavku, použite nový kľúč.

Správy

Objekt správy

Kde sa messages objavuje:

Závažnosť a čo od vás žiada

Stav checkoutu vyplýva z jeho správ: akákoľvek správa error so závažnosťou recoverable z neho robí incomplete; inak je requires_escalation a nesie payment_required. Správy checkoutu idú v tomto poradí: správy k položkám, správy k zľavovým kódom, potom to, čo checkoutu chýba, a payment_required na konci.

Správy k položkám

Objavujú sa v košíku aj checkoute pri vytvorení a pri každom zápise, ktorý posiela line_items (aj keď zmena jazyka položky nanovo nacení). Sú iba v odpovedi na zápis, ktorý ich spôsobil: v tej odpovedi je položka už odstránená alebo znížená, takže ďalšie čítanie checkoutu môže vrátiť requires_escalation bez nich.

<id> je item.id tak, ako ste ho poslali (bez okrajových medzier). Správy o jednom variante — cannot be bought right now, vat_mix_not_allowed a out_of_stock — uvádzajú prvé id, ktoré ste pre daný variant poslali.

Správy k zľavovým kódom

Objavujú sa pri vyjednanom rozšírení zliav, pri každom vytvorení a PUT košíka či checkoutu vrátane prevodu košíka. Kódy sa skúšajú v poradí, v akom ste ich poslali, a uplatní sa prvý, ktorý obchod prijme.

V relácii, z ktorej sa odstránili všetky položky, sa kódy posudzujú voči súčtu 0: kód s minimálnou sumou objednávky dostane discount_code_user_ineligible a každý iný kód, ktorý obchod prijme, sa uplatní bez správy, no nič neodpočíta, takže discounts.applied zostane prázdne.

<i> sa počíta v zozname tak, ako ho API uchováva: bez duplicít (porovnaných bez ohľadu na veľké a malé písmená) a bez prázdnych kódov. Odmietnutý kód zostáva uložený a pri ďalšom zápise sa skúsi znova; ak ho chcete zahodiť, pošlite discounts.codes bez neho.

Pripravenosť checkoutu

Určuje sa nanovo pri každom vytvorení, PUT, GET a POST …/complete otvoreného checkoutu — keď si ho kupujúci odniesol do obchodu, opakuje sa namiesto toho posledná odpoveď pred odovzdaním. Správy k doručeniu sa objavujú iba pri vyjednanom rozšírení fulfillment.

Uzavreté a odovzdané relácie

Tieto správy môžu prísť aj na zápis, ktorý sa predbiehal s objednávkou alebo s uplynutím platnosti: odpoveďou je potom relácia tak, ako je teraz — uzavretá.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.fulfillment": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08"
        }
      ]
    },
    "payment_handlers": {}
  },
  "id": "3d7b9e2a-6f14-4c58-9b3e-8a2f1c6d4e97",
  "buyer": {
    "email": "jana.novakova@example.com",
    "last_name": "Nováková",
    "first_name": "Jana",
    "phone_number": "+421 905 123 456"
  },
  "links": [
    {
      "url": "https://shop.example.com/obchodne-podmienky",
      "type": "terms_of_service",
      "title": "Obchodné podmienky"
    },
    {
      "url": "https://shop.example.com/ochrana-osobnych-udajov",
      "type": "privacy_policy",
      "title": "Ochrana osobných údajov"
    }
  ],
  "status": "requires_escalation",
  "totals": [
    {
      "type": "subtotal",
      "amount": 71880
    },
    {
      "type": "discount",
      "amount": -5844,
      "display_text": "JESEN10"
    },
    {
      "type": "fulfillment",
      "amount": 490
    },
    {
      "type": "total",
      "amount": 66526
    }
  ],
  "context": {
    "language": "sk",
    "address_country": "SK"
  },
  "currency": "EUR",
  "messages": [
    {
      "code": "payment_required",
      "type": "error",
      "content": "Payment is completed on the shop website — continue there to place the order",
      "severity": "requires_buyer_input"
    },
    {
      "type": "warning",
      "code": "handed_off",
      "content": "The buyer continued on the shop: the items are in the shop’s cart now and this session is no longer changed"
    }
  ],
  "discounts": {
    "codes": [
      "JESEN10"
    ],
    "applied": [
      {
        "code": "JESEN10",
        "title": "JESEN10",
        "amount": 5844,
        "method": "across"
      }
    ]
  },
  "expires_at": "2026-10-27T09:21:30.551Z",
  "line_items": [
    {
      "id": "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
      "item": {
        "id": "1e8a6c4f-2b93-4d71-9f05-6a3c8e2b1d47",
        "price": 69900,
        "title": "Trek Marlin 5",
        "image_url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-5-modra.webp"
      },
      "totals": [
        {
          "type": "subtotal",
          "amount": 69900
        },
        {
          "type": "total",
          "amount": 69900
        }
      ],
      "quantity": 1
    },
    {
      "id": "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49",
      "item": {
        "id": "b5f81c3d-6e49-4a2b-8d73-9c0e4f1a6b25",
        "price": 990,
        "title": "Fľaša na vodu 750 ml"
      },
      "totals": [
        {
          "type": "subtotal",
          "amount": 1980
        },
        {
          "type": "total",
          "amount": 1980
        }
      ],
      "quantity": 2
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "shipping",
        "type": "shipping",
        "groups": [
          {
            "id": "default",
            "options": [
              {
                "id": "0c5e8a3f-7b21-4d96-8f4c-9e2a6d1b3c75",
                "title": "GLS kuriér",
                "totals": [
                  {
                    "type": "total",
                    "amount": 490
                  }
                ],
                "description": "Doručenie na adresu do 1–2 pracovných dní"
              },
              {
                "id": "6b2d9f4e-3a17-4c68-9d5b-1f8e3a7c2b40",
                "title": "Packeta – výdajné miesto",
                "totals": [
                  {
                    "type": "total",
                    "amount": 290
                  }
                ],
                "description": "Delivery in 2–3 business days"
              }
            ],
            "line_item_ids": [
              "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
              "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49"
            ],
            "selected_option_id": "0c5e8a3f-7b21-4d96-8f4c-9e2a6d1b3c75"
          }
        ],
        "destinations": [
          {
            "id": "destination",
            "last_name": "Nováková",
            "first_name": "Jana",
            "postal_code": "811 01",
            "street_address": "Hlavná 12",
            "address_country": "SK",
            "address_locality": "Bratislava"
          }
        ],
        "line_item_ids": [
          "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
          "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49"
        ],
        "selected_destination_id": "destination"
      }
    ]
  },
  "continue_url": "https://shop.example.com/ucp/continue/9bbd3dedf887f93c6287fa7f4b8de141501155714c3b2050bb83551e36ec780b"
}

Správy katalógu

Ako správy ukázať kupujúcemu

content je v angličtine a je písaný pre vývojárov. Text pre kupujúceho zostavte z code a path v jeho jazyku a content si nechajte pre logy. Každú správu pokryjú tri pravidlá:

1. Chyby recoverable riešte sami tak, že pošlete to, na čo ukazuje path.
2. Varovania ukážte ako zmenu, ktorú opisujú — „na sklade sú iba 2 kusy, množstvo sme znížili“ — pretože odpoveď už obsahuje zmenený stav.
3. requires_buyer_input odovzdajte kupujúcemu spolu s continue_url.

Môžu pribudnúť ďalšie kódy. Neznámy kód posúďte podľa type a severity, nikdy kvôli nemu nezlyhajte.

Odpovede, ktoré nie sú JSON

Webový server

Webový server pred každým obchodom tieto situácie vybaví sám, skôr než požiadavku uvidí API. Telom je krátka HTML stránka, nie JSON.

<html>
<head><title>429 Too Many Requests</title></head>
<body>
<center><h1>429 Too Many Requests</h1></center>
<hr><center>nginx</center>
</body>
</html>

Cesty, ktoré webový server do API neposiela — /UCP/… veľkými písmenami, /.well-known/ucp/ s lomkou na konci, /ucp bez zvyšku — skončia na webových stránkach obchodu a aj tie vrátia HTML. Používajte cesty presne tak, ako sú zverejnené.

Cesty odovzdania

continue_url (GET /ucp/continue/<token>) otvára prehliadač kupujúceho a jeho stránka sama posiela POST /ucp/continue/<token>. Váš klient nevolá ani jedno, no kupujúci vám tieto odpovede môžu nahlásiť:

Pri 5xx, 429 alebo prerušenom spojení stránka požiadavku zopakuje ešte dvakrát, po 1 a po 2 sekundách, a potom pošle prehliadač do pokladne, do košíka alebo na úvodnú stránku obchodu bez položiek. Ak vaša platforma zisťuje stav relácie, ktorú kupujúci práve otvára, majte rozpracovanú najviac jednu požiadavku, aby sa jeho požiadavka dostala na rad.

Čo zapisovať do logov

API nevracia žiadne id požiadavky. Pri každom volaní si zapíšte aspoň čas v UTC, hostiteľa, metódu a cestu, stav HTTP, code (alebo kódy správ) a vlastné korelačné id. Toto id posielajte aj ako X-Request-ID: webový server obchodu ho zapíše do svojho prístupového logu (späť ho nevracia), takže sa problém dá na strane Monokaida dohľadať. Nedávajte doň nič tajné. Id košíka a checkoutu sú prístupové údaje: nedávajte ich do logov, ktoré čítajú tretie strany — pozrite Bezpečnosť a ochrana údajov.