Error codes · Commerce · Reference — OmniRetailConnect Docs

Error codes at a glance

REST errors are {"error": {"code", "message"}} with the status shown. MCP tool errors carry the same code values inside a tools/call result with isError: true; MCP transport errors are plain HTTP or JSON-RPC errors. Branch on the code, not on the message.

Error codes
Code	REST status	Meaning
`unauthenticated`	401	REST: missing, malformed, unknown, revoked or expired token, or a token without the `api` channel. Without a valid token every request under `/api/v1` (any method, any path, the bare prefix, malformed percent-encoding or invalid UTF-8) answers this identical `401`; only `GET /api/v1/openapi.json` is public. MCP answers `401` `{"message":"Unauthorized."}` for the same causes (channel `mcp`).
`forbidden_scope`	403	The token lacks the scope for the endpoint, tool or option (for example email search without `commerce.read.pii`). MCP: tool error with the same code. An MCP write tool is not shown to a token without its write scope, and calling it answers JSON-RPC `-32602`.
`https_required`	403	Production and the request is not secure. MCP: HTTP `403`, JSON-RPC `-32600`. If you already use https, the operator should check the reverse-proxy configuration.
`not_found`	404	The resource does not exist, or the path is unknown (REST, with a valid token). A switched-off interface answers the shop's normal 404 for `GET` and `405` for `POST`, `PUT`, `PATCH` and `DELETE`. MCP: tool error with the same code for a missing product, SKU, image, order or category.
`method_not_allowed`	405	REST: a method the path does not support; `Allow` lists the methods of the path (`GET, HEAD`, plus `POST`, `PUT`, `PATCH` or `DELETE` on the write paths). MCP: `GET` or `DELETE` on the endpoint (use `POST`).
`—`	413	MCP only: request body above 256 KiB (64 KiB before server 1.6.0).
`uri_too_long`	414	REST only: URL longer than the URL cap (4096 bytes by default).
`conflict`	409	Writes (MCP write tools and REST write endpoints): stock is managed by an external inventory provider (`set_stock`), the shop gets its products from the PIM (`create_product`), an order, discount or page is in a state the action does not allow (an order that is not an unpaid draft, a used discount code, a discount code that is taken, a stale `expected_updated_at` on a page, an `idempotency_key` reused with other data), or the data changed during the call or stayed locked by another change. MCP: tool error with the same code.
`invalid_argument`	422	Failed validation, unknown parameter or argument, bad cursor, missing or conflicting identifiers, range too long; for write tools also a taken SKU, name, code or slug, a refused image URL, a date that does not exist, or a rule of the thing you write (a sale price not below the regular price, a block that breaks the rules of its type). MCP: tool error with the same code.
`field_owned_by_pim`	422	Writes (MCP write tools and REST write endpoints): the field, image or category placement belongs to the PIM on a product linked to the PIM. MCP: tool error with the same code.
`too_many_requests`	429	A per-IP or per-token rate limit was exceeded. Has `Retry-After`. MCP body: `{"message":"Too Many Attempts."}`. Branch on the status code and `Retry-After`, not on the message text. MCP write tools also answer this code as a tool error when the token made more than 30 write calls in a minute (`Too many write requests. Try again in a minute.`, no `Retry-After`).
`internal_error`	500	Unexpected failure. The message is always `An internal error occurred.` MCP: tool error with the same code.

Details and examples: Errors and status codes.

MCP JSON-RPC codes

JSON-RPC error codes
Code	Meaning
`-32700`	Unparsable JSON (HTTP `400`).
`-32600`	The body is not a JSON-RPC object (`400`), HTTPS is required (`403`), or the body is too large (`413`).
`-32601`	Unknown method (`404`).
`-32602`	Invalid `params` for `tools/list` or `tools/call`, (`400`); a `tools/call` for an unknown tool name also answers `-32602`.