What do 401, 403, and 422 error responses from the External API mean, and how do I resolve them?
Last updated: October 2, 2026
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
Authorizationheader 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:
Confirm every request includes the header
Authorization: Bearer <your-token>— note theBearerprefix with a space.Also include
Content-Type: application/jsonandAccept: application/json.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.
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.
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) allowsGETrequests 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:
If you need to write data (create orders, update products, etc.), obtain an OAuth token that includes the
luminous:writescope, or switch to a standard API token.If you only need to read data, confirm you are not accidentally calling a write endpoint.
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:
Read the
errorsobject carefully — each key is the exact field path that failed, and the value is an array of human-readable messages describing what is wrong.Fix each field listed in
errorsand resubmit the request.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.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.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
errorsmessage alone.Errors appear suddenly on requests that previously succeeded with no changes on your side.