Errors

The OMS API can report problems in two distinct ways. It is important to handle both.

GraphQL errors (HTTP 200)

When the request reaches the GraphQL layer, errors are returned with HTTP status 200 and an errors array in the body (this is standard GraphQL behaviour). The data field may be null or partial.

{
  "errors": [
    {
      "message": "An object of type Query brands was hidden due to missing permissions. You must be granted access to provided permissions.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["brands"],
      "extensions": {
        "permission_required": "brand:query:brands",
        "code": "UNAUTHORIZED"
      }
    }
  ],
  "data": { "brands": null },
  "extensions": {
    "queryComplexity": 2,
    "bucketBalance": 9998,
    "bucketRestoreRate": 100
  }
}

Each error may include a message, its locations in the query document, a path, and an extensions.code. The top-level extensions are the usual rate limiting metadata, reported whenever the operation executes. Always inspect the errors key even when the HTTP status is 200.

Common error codes

The most frequent extensions.code values (not an exhaustive list):

extensions.code	Meaning	Example message
UNAUTHORIZED	The token lacks the permission required by the operation. The required permission is in extensions.permission_required.	An object of type Query brands was hidden due to missing permissions.
NOT_FOUND	A record addressed by the operation does not exist (e.g. an order(id:) or a mutation targeting an unknown id or code).	Record not found.
MULTIPLE_RECORD_FOUND	A lookup by code that expects a single record matched more than one (e.g. findWarehouse(code:)).	Multiple records found.
BAD_REQUEST	A business rule rejected the operation: invalid state, invalid status transition, a requirement not met. Most business-rule errors share this code, so the specific cause is only in the message.	Billing recipient is required
DUPLICATED_ORDER	An orderImport was rejected because the number already exists for the channel. Distinct from BAD_REQUEST, so a duplicate can be intercepted by code.	Order 123456789 already exists for channel ECOM
VALIDATION_ERROR	The submitted data failed a validation on save (e.g. a returned line with quantityCompliant greater than quantityReceived).	Record is invalid.
FILTER_INVALID	A match filter value does not follow the <version>/<pattern>/<options> format (see Filtering).	Invalid match filter syntax. Expected v1/<v1_pattern>.
MAX_COMPLEXITY_EXCEEDED	The query complexity exceeds the current bucket balance; the request is rejected without executing and without consuming points (see Rate limiting).	Query 'heavy' has complexity of 16880, which exceeds bucket balance of 5848
INTERNAL_SERVER_ERROR	An unexpected server-side error occurred while resolving the operation.	Internal server error.

When the document itself is invalid (unknown field or argument, missing required argument, wrong type, an object field selected without a subselection, a @oneOf input with zero or several members), GraphQL rejects it before execution: the response has no usable data, and the error carries a camelCase code (e.g. undefinedField, missingRequiredArguments) with a message describing the problem. These errors point at a bug in the client's query: fix the document, retrying it cannot succeed.

Authentication errors (HTTP 403)

If the token is missing or invalid, the request is rejected before the GraphQL layer: the response has HTTP status 403 and a plain JSON body — not the GraphQL errors envelope. The message differs between the two cases.

With no Authorization header:

{ "message": "Must provide token" }

With a header present but a token that is not valid:

{ "message": "Invalid token" }

So a client should treat a 403 with a message field as an authentication failure, distinct from a GraphQL errors response returned with 200.