Error Codes

This is the authoritative reference for the error codes this service returns. Error messages are localized in English, French, and Arabic.

Code format

EQ-- — e.g. EQ-POL-4040001:

  • EQ — platform prefix.
  • — POL (Policy), PRL (Policy-Role mapping), USR (JWT auth / authorization, shared with user domain), SED (Service privilege catalog / master SEed Data).
  • — the 3-digit HTTP status baked into the code (400, 401, 403, 404, 409, 422, 500).
  • — 4-digit sequence within that domain+status.

Error response shape

Every error response carries the error code both in the response body and in an Error-Code header. The body contains the following fields:

Field Meaning
errorCode The EQ-- code identifying the error
errorMessage The localized, human-readable message
validations Optional array of detail strings when multiple validation messages apply
details Optional field-level messages, present only when an external policy validator supplies them
  • A single detail message replaces errorMessage; multiple detail messages go into validations.
  • Authentication/authorization (401/403) responses initially carry only the error code; the localized message is added before the response is sent.

HTTP status quick reference

HTTP Meaning Example codes
400 Bad request / validation EQ-POL-4000001, EQ-PRL-4000001
401 Authentication failed EQ-USR-4010001 … EQ-USR-4010015
403 Authorization failed EQ-USR-4030004, EQ-USR-4030005
404 Not found EQ-POL-4040001, EQ-PRL-4040001, EQ-SED-4040001
409 Conflict EQ-POL-4090001, EQ-POL-4090002, EQ-PRL-4090001
422 Unprocessable entity EQ-POL-4220001
500 Internal server error EQ-POL-5000001, EQ-PRL-5000001

Policy errors (EQ-POL-…)

Code HTTP Constant When does this happen? How to resolve
EQ-POL-4040001 404 POLICY_NOT_FOUND Policy id not found, or found but belongs to a different businessId; also when specific policyIds return nothing Verify the id and that it belongs to the supplied businessId
EQ-POL-4090001 409 POLICY_ALREADY_EXISTS Creating/renaming to a policyName that already exists within the same business Choose a unique policy name for that business
EQ-POL-4000001 400 INVALID_POLICY_NAME Name missing, non-string, or contains chars outside [a-zA-Z0-9 _-] Use only alphanumerics, spaces, hyphens, underscores
EQ-POL-4000002 400 INVALID_POLICY_DESCRIPTION Description not a string or > 500 chars Keep description ≤ 500 chars
EQ-POL-4000003 400 INVALID_POLICY_STATEMENTS statements missing/empty or > 50 items, or an item is malformed Provide 1–50 valid statements
EQ-POL-4000004 400 INVALID_POLICY_EFFECT Effect is not Allow or Deny Set Effect to Allow or Deny
EQ-POL-4000005 400 INVALID_POLICY_ACTIONS Action missing/empty or an item is not a non-empty string Provide at least one valid action string
EQ-POL-4000006 400 INVALID_POLICY_RESOURCES Resource is an empty string / empty array / wrong type Provide a non-empty string or non-empty array of strings
EQ-POL-4000007 400 POLICY_NAME_TOO_LONG Name > 100 chars Shorten the name to ≤ 100 chars
EQ-POL-4000008 400 INVALID_ACTION_PATTERN Action not in service:action colon format (matches ^[a-zA-Z0-9_-]+:[a-zA-Z0-9_*-]+$) Use colon format, e.g. user:create, order:view:*
EQ-POL-4000009 400 MISSING_REQUIRED_FIELDS Schema-level: a required field (e.g. Effect/Action) is missing Add the missing field
EQ-POL-4000010 400 POLICY_NAME_TOO_SHORT Trimmed name < 3 chars Use a name of at least 3 chars
EQ-POL-4220001 422 POLICY_VALIDATION_FAILED Generic validation failure (bad JSON body, unknown fields, minItems, custom-validator failure) Inspect errorMessage/validations for specifics
EQ-POL-4000011 400 INVALID_POLICY_ID :id is not a valid Mongo ObjectId Provide a valid 24-hex ObjectId
EQ-POL-4000012 400 INVALID_POLICY_STATUS On create, status set to anything other than ACTIVE Omit status or set it to ACTIVE
EQ-POL-4000013 400 INVALID_POLICY_STATUS_UPDATE On update, status not one of ACTIVE/INACTIVE (also enum schema violation) Use ACTIVE or INACTIVE
EQ-POL-4000014 400 POLICY_ID_REQUIRED :id path param empty/whitespace Supply the policy id
EQ-POL-4000015 400 BUSINESS_ID_VALUE_REQUIRED businessId empty/≤ 0 or not an integer Provide a positive integer businessId
EQ-POL-4000016 400 NO_UPDATE_FIELDS_PROVIDED PATCH body empty / no fields Include at least one updatable field
EQ-POL-4090002 409 POLICY_ALREADY_DELETED Updating/deleting a policy whose status is already DELETED Operate on a non-deleted policy
EQ-POL-4000020 400 INVALID_CONDITION_OPERATOR Condition uses an operator not in the 108-operator set Use a supported IAM operator
EQ-POL-4000021 400 INVALID_CONDITION_STRUCTURE Condition is an array/primitive, or an operator block is not an object Use { Operator: { key: value } } object shape
EQ-POL-4000022 400 INVALID_CONDITION_KEY Condition key empty / not a string Provide a non-empty string key
EQ-POL-4000023 400 INVALID_CONDITION_VALUE Condition value is a nested object/null (not string/number/boolean or arrays of these) Use primitive or array-of-primitive values
EQ-POL-5000001 500 POLICY_INTERNAL_SERVER_ERROR Unexpected server/DB failure in policy ops (also the default fallback) Retry; inspect server logs

Policy-Role mapping errors (EQ-PRL-…)

Code HTTP Constant When does this happen? How to resolve
EQ-PRL-4040001 404 ROLE_MAPPING_NOT_FOUND Role id not found on get/update/delete Verify the role id
EQ-PRL-4090001 409 ROLE_MAPPING_ALREADY_EXISTS roleName already exists for this businessId Use a unique role name per business
EQ-PRL-4000001 400 INVALID_ROLE_MAPPING_OBJECT_ID On create, status provided is not ACTIVE/INACTIVE (reuses this code) Use a valid status
EQ-PRL-4000002 400 INVALID_ROLE_MAPPING_NAME Role name < 3 or > 128 chars, bad chars, or attempt to change immutable roleName on update Provide a valid name; do not send roleName in PATCH
EQ-PRL-4000003 400 INVALID_ROLE_MAPPING_DESCRIPTION roleDescription > 500 chars Shorten description
EQ-PRL-4000004 400 INVALID_ROLE_MAPPING_POLICIES policies empty / > 100 / duplicate / not 24-hex ObjectIds / referenced policy missing Provide valid, existing, unique policy ObjectIds
EQ-PRL-4000005 400 INACTIVE_POLICY_IN_ROLE A referenced policy is INACTIVE Only assign ACTIVE policies
EQ-PRL-4000007 400 INVALID_ROLE_ID :id or a mappingIds value is not a valid ObjectId Provide valid ObjectIds
EQ-PRL-5000001 500 ROLE_MAPPING_INTERNAL_SERVER_ERROR Unexpected server/DB failure in role ops Retry; inspect logs

Note: a message for EQ-PRL-4220001 (“Policy role validation failed”) exists in the localized message set, but this code is not part of the active error catalog — it is an orphan message key.

JWT authentication & authorization errors (EQ-USR-…)

Produced by the shared JWT authentication layer (these codes are surfaced through the Auth Service response layer).

Code HTTP Constant When
EQ-USR-4010001 401 MISSING_AUTH_TOKEN No bearer token supplied
EQ-USR-4010002 401 INVALID_AUTH_TOKEN Token invalid/malformed
EQ-USR-4010003 401 INVALID_TOKEN_CLAIMS Token claims invalid
EQ-USR-4010006 401 TEST_TOKEN_DISABLED Test tokens not allowed in this env
EQ-USR-4010007 401 TEST_TOKEN_ENV_MISMATCH Test token env mismatch
EQ-USR-4010008 401 TEST_TOKEN_KEY_MISSING Test-token private key not configured
EQ-USR-4010009 401 TEST_TOKEN_INVALID Test-token validation failed
EQ-USR-4010010 401 TOKEN_EXPIRED Token expired
EQ-USR-4010011 401 TOKEN_INVALID_SIGNATURE Bad signature
EQ-USR-4010012 401 TOKEN_MALFORMED Malformed token
EQ-USR-4010013 401 TOKEN_INVALID_ISSUER Issuer not allowed
EQ-USR-4010014 401 TOKEN_INVALID_AUDIENCE Audience invalid
EQ-USR-4010015 401 TOKEN_GENERIC_INVALID Generic token validation failure
EQ-USR-4030004 403 INSUFFICIENT_PERMISSIONS Missing required privilege or not isAdmin
EQ-USR-4030005 403 AUTHORIZATION_FAILED Authorization check failed

Service Privilege Catalog errors (EQ-SED-…)

Code HTTP Constant When How to resolve
EQ-SED-4040001 404 SERVICE_PRIVILEGE_CATALOG_NOT_FOUND GET /v1/service-privileges?serviceName=X where no masterseeddata doc matches X Use a known serviceName, or seed the catalog

Revision History
2026-08-05 | AN – Page created and uploaded the contents