Success and errors

Recognize a successful response

The common OrionMarketplace backend API envelope has three fields. Confirm success only when all three checks below pass.

• 200–299 — The HTTP request completed successfully.
• success_message !== null && success_message !== '' — A non-empty success message was returned.
• form_errors === null — The backend returned no form errors.

{
  "form_errors": null,
  "success_message": "OK",
  "page_data": {}
}

This is an example envelope. The contents of page_data depend on the endpoint; it may also be null. Do not compare the message with “OK”: its text is translated and can vary.

A missing, null or empty success message does not confirm success. Do not show a completed action in that case. Errors take priority even if a success message is also present. Missing form_errors is an invalid envelope, not the same as null.

Display form errors

The OrionMarketplace backend can return validation and business errors with HTTP 200. Always inspect the JSON envelope before reading the result or showing a success notification.

{
  "form_errors": {
    "email": [
      {
        "message": "Enter a valid email address.",
        "code": "invalid"
      }
    ],
    "__all__": [
      {
        "message": "Correct the highlighted fields.",
        "code": ""
      }
    ]
  },
  "success_message": null,
  "page_data": null
}

form_errors.email

Show each message next to its corresponding input.

form_errors.__all__

Show these messages above the form or in the action result.

Each field contains an array of message/code objects. Keep every message, render it as plain text, and preserve the user’s input. Codes may be empty; never use translated message text as a machine-readable condition.

HTTP statuses

These statuses are verified in the OrionMarketplace backend’s API handlers and middleware. The same status can have several causes. Some middleware and server responses are HTML or plain text instead of the common JSON envelope.

The current quota middleware checks the allowance after the endpoint has run. A 453 response does not prove that a write was cancelled. Confirm its outcome before retrying.

Gateway and network failures

502 / 503 — The storefront gateway (app/api/[...orionplace]/route.ts) answers 502 when it cannot connect to OrionMarketplace and 503 when the connection settings are missing or invalid. Handle these separately from form errors.

A failed connection has no HTTP response. Handle unreadable JSON and unexpected content types separately too. Keep the status when available and never assume every error body follows the API envelope.

When to show an error page

Replace the page when its essential data cannot be loaded. An unavailable backend is not an empty product collection and does not mean that the requested page is missing.

The server sends 503 with Cache-Control: private, no-store; a failed browser navigation shows the same error view.

Error handling, setup, type and endpoint references, and the Application Load overview remain accessible without initialization. A later failed form request does not activate this page.

The React starter keeps an Application Load failure in useOrionplace(selectFailure), and useOrionplace(selectStatus) is error. Every storefront page is then replaced by the localized error page with HTTP 503 and a Retry button (proxy.ts sets the status); an unknown address keeps its 404 page. The table above describes when a storefront should replace its page instead of showing an error beside a component.

Renewal, errors and session changes

Renew the CSRF cookie

POST /api/csrf_renew — send an empty JSON object through the same-origin gateway to obtain or renew the CSRF cookie, then read its current value. Renewal does not sign the customer in.

419 · page_data.csrf === false — this is the backend’s CSRF-rejection response. Accept any replacement response cookie, renew if necessary, then offer an explicit retry. Do not automatically repeat payments, orders or other mutations.

403 — a forbidden response can also mean insufficient permissions or a rejected origin. Do not treat every forbidden response as an expired CSRF token.

After sign-in or sign-out

reset() → await refresh() — after the backend confirms sign-in or sign-out, call reset() and await refresh() from useOrionplaceAppLoad(): the data and methods reload for the new session.

stores/orionplace.ts — reset and refresh change application data. They do not log the customer in or out and do not delete the browser’s cookies.

When a session ends during a request

In the React starter the shared client in lib/orionplace/api.ts checks every request it sends, including CSRF renewal, and reacts to HTTP 401 as shown below.