Symptom

Your integration receives an HTTP error response — 401, 403, or 422 — instead of the expected data. The response body is a JSON object with a message field, and for 422 errors an additional errors object listing the specific problems.

Why it happens and how to resolve it

401 Unauthorized

What the response looks like:

{ "message": "Unauthorized" }

Cause: The API could not verify your identity. This happens when:

  • The Authorization header is missing entirely.
  • The bearer token value is incorrect, has been deleted, or has never existed in Luminous.
  • You are using an OAuth access token that has been revoked, has expired, or was issued for a different tenant's subdomain.

How to resolve:

  1. Confirm every request includes the header Authorization: Bearer <your-token> — note the Bearer prefix with a space.
  2. Also include Content-Type: application/json and Accept: application/json.
  3. Log in to Luminous, navigate to Settings → API Tokens, and verify the token you are using still exists and is active. If it was deleted, generate a new one and update your integration.
  4. If you are calling the API from a different subdomain than the one your token was generated for, switch to the correct subdomain. Tokens are tenant-specific.
  5. If your organization uses OAuth access tokens, check that the token has not expired and that it was issued against the correct tenant.

403 Forbidden

What the response looks like:

{ "message": "Insufficient scope" }

Cause: Your token was recognized and is valid, but it does not carry the permissions needed for the operation you attempted. This applies to OAuth tokens specifically:

  • Read-only scope (luminous:read) allows GET requests only.
  • Write scope (luminous:write) is required for any request that creates or modifies data (POST, PUT, PATCH, DELETE).

A standard API token (the kind generated from Settings → API Tokens) does not produce 403 errors this way — this response is exclusive to OAuth access tokens that were issued with a restricted scope.

How to resolve:

  1. If you need to write data (create orders, update products, etc.), obtain an OAuth token that includes the luminous:write scope, or switch to a standard API token.
  2. If you only need to read data, confirm you are not accidentally calling a write endpoint.
  3. Contact your Luminous account administrator to request a token with the appropriate scope level.

422 Unprocessable Entity

What the response looks like:

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": ["The field name is required."],
    "items.0.quantity": ["Item quantity must be greater than 0."],
    "ship_to.name": ["Shipping name is required."]
  }
}

Cause: Your request body was received and authenticated successfully, but one or more fields failed validation. Common reasons include:

  • A required field is missing (e.g. no order_number, no line items).
  • A field contains a value that does not match the expected format or allowed list (e.g. an invalid status string, a non-numeric quantity).
  • A nested field in an array is invalid (the field key will include the array index, such as items.0.sku).
  • A date parameter is in the wrong format.
  • You supplied a lot-related field for a product that does not have lot tracking enabled.
  • A configurable validation rule set up on your account requires a field that is absent or blank.

How to resolve:

  1. Read the errors object carefully — each key is the exact field path that failed, and the value is an array of human-readable messages describing what is wrong.
  2. Fix each field listed in errors and resubmit the request.
  3. For nested arrays (e.g. items.0.quantity), the number in the path is the zero-based index of the item in the array — check that specific line.
  4. For date fields, use the format documented for that endpoint. Most date-only fields use YYYY-MM-DD; date-time fields with a time component should include a UTC offset (e.g. 2026-04-23T20:16:03.000000Z) to avoid timezone ambiguity.
  5. If the error mentions a field you did not include in your request at all, check whether your account has a configurable validation rule that makes that field mandatory under certain conditions — contact support if you are unsure which rule is triggering.

When to contact support

  • You receive a 401 but your token is present in Settings → API Tokens and the header looks correct.
  • You receive a 403 and you believe the operation should be permitted by your token's scope.
  • A 422 error references a field or rule you cannot identify from the errors message alone.
  • Errors appear suddenly on requests that previously succeeded with no changes on your side.