Error Codes

Format: EQ-PROMO-{HTTP-STATUS}{SEQ} — e.g. EQ-PROMO-4040001 = HTTP 404, sequence 0001. Where a status is not mapped, the service falls back to parsing the 3-digit status embedded in the code.

Error response shape: every error returns an errorCode, a human-readable errorMessage, and an optional validations array of detail strings.

The error code is also returned in the Error-Code response header. The errorMessage is localized when a translation exists, otherwise the code is echoed.

HTTP status quick reference

HTTP Meaning Example code
400 Bad Request (validation/format) EQ-PROMO-4000002
401 Unauthorized (auth failure — from JWT plugin) EQ-PROMO-4010001 (schema example)
403 Forbidden (insufficient privilege) EQ-PROMO-4030001
404 Not Found EQ-PROMO-4040001
409 Conflict (duplicate / concurrent / reserved) EQ-PROMO-4090001
422 Unprocessable Entity (business-rule / rule-compile) EQ-PROMO-4220001
500 Internal Server Error EQ-PROMO-5000099
503 Service Unavailable (schema example only) EQ-PROMO-5030001

401 and 503 appear as OpenAPI response examples but are not defined as service error codes — 401 is produced by the JWT auth plugin, not this service.

400 — Validation / format

Code HTTP Constant When Resolution
EQ-PROMO-4000001 400 PROMO_DATA_REQUIRED Request body missing where promo data required Supply the request body
EQ-PROMO-4000002 400 INSTANCE_ID_REQUIRED instanceId query param missing Add ?instanceId=...
EQ-PROMO-4000003 400 INVALID_REQUEST_BODY_FORMAT Body is not valid JSON/shape Send well-formed JSON
EQ-PROMO-4000004 400 INVALID_REQUEST_FIELDS Ajv schema field validation failed Fix the flagged fields (validations[])
EQ-PROMO-4000005 400 INVALID_QUERY_STRING Query string malformed Correct query params
EQ-PROMO-4000006 400 QUERY_STRING_REQUIRED Required query string absent Provide required query params
EQ-PROMO-4000007 400 INVALID_ID Identifier fails format check Use a valid identifier
EQ-PROMO-4000008 400 INVALID_INSTANCE_ID instanceId malformed Use a valid instance id
EQ-PROMO-4000009 400 INVALID_PAGINATION Bad page/limit values Use valid pagination
EQ-PROMO-4000010 400 INVALID_DATE_RANGE start/end date range invalid Fix the date range
EQ-PROMO-4000019 400 ACTIVE_DATE_IN_PAST Active-from date is in the past Use a future/current date
EQ-PROMO-4000011..017 400 INSTANCE_NAME_ / INSTANCE_INVALID_ Instance name/status/description/field-type validation Correct the instance field
EQ-PROMO-4000018 400 EMPTY_REQUEST_BODY Empty body on create/update Send a non-empty body
EQ-PROMO-4000020 400 INVALID_CUSTOMER_ID_FORMAT customerId fails pattern Use valid customer id
EQ-PROMO-4000021 400 INVALID_PROMOTION_ID_FORMAT promotionId fails pattern Use valid promotion id
EQ-PROMO-4000022 400 PROMOTION_LIST_NAME_INVALID_TYPE List name not a string Send name as a string

403 / 404

Code HTTP Constant When Resolution
EQ-PROMO-4030001 403 AUTH_INSUFFICIENT_PERMISSIONS Missing privilege or isAdmin Grant the promotion:* privilege / admin role
EQ-PROMO-4040001 404 PROMO_NOT_FOUND Promotion id not found Verify id + instanceId
EQ-PROMO-4040002 404 INSTANCE_NOT_FOUND Instance not found Verify instanceId
EQ-PROMO-4040010 404 PROMO_VERSION_NOT_FOUND Version snapshot not found Check versionId
EQ-PROMO-4040020 404 GROUP_NOT_FOUND Group not found Verify group id
EQ-PROMO-4040021 404 GROUP_MEMBER_PROMOTION_NOT_FOUND Assigning/unassigning missing promotion Verify promotionId
EQ-PROMO-4040022 404 GROUP_VERSION_HISTORY_EMPTY No version history for group N/A
EQ-PROMO-4040030 404 PROMOCODE_NOT_FOUND Code not found Verify code/list
EQ-PROMO-4040031 404 PROMOCODE_NO_REDEMPTION_FOUND Reverse with no redemption Nothing to reverse
EQ-PROMO-4040032 404 PROMOCODE_NOT_ASSIGNED Unassign a non-assigned code N/A
EQ-PROMO-4040040 404 WORKFLOW_ENTITY_NOT_FOUND Workflow target entity missing Verify entity id
EQ-PROMO-4040050 404 PROMOTION_LIST_NOT_FOUND List not found Verify list id

409 — Conflict

Code HTTP Constant When Resolution
EQ-PROMO-4090001 409 PROMO_NAME_ALREADY_EXISTS Duplicate promotion name Use a unique name
EQ-PROMO-4090002 409 PROMOCODE_ALREADY_REDEEMED Code already redeemed Use another code
EQ-PROMO-4090003 409 INSTANCE_NAME_ALREADY_EXISTS Duplicate instance name Use a unique name
EQ-PROMO-4090010 409 PROMO_CANNOT_DELETE_ACTIVE Deleting an active promotion Pause/archive first
EQ-PROMO-4090011 409 PROMO_CONCURRENT_MODIFICATION Optimistic-lock version conflict Reload and retry
EQ-PROMO-4090020 409 GROUP_CANNOT_DELETE_ACTIVE Deleting an active group Pause/archive first
EQ-PROMO-4090021 409 GROUP_HAS_ACTIVE_MEMBERS Group still has active members Remove members first
EQ-PROMO-4090030 409 PROMOCODE_RESERVED_BY_OTHER Code reserved/blocked by another cart Wait for TTL / use another
EQ-PROMO-4090031 409 PROMOCODE_NO_AVAILABLE_CODE No unassigned code left in list Generate more codes
EQ-PROMO-4090032 409 PROMOCODE_ALREADY_ASSIGNED Code already assigned Use another code

422 — Business rule / rule engine

Code HTTP Constant When Resolution
EQ-PROMO-4220001 422 PROMO_VALIDATION_FAILED Domain validation failed (see validations[]) Fix flagged issues
EQ-PROMO-4220002 422 PROMO_INVALID_STATUS_TRANSITION Illegal status change Use a valid transition
EQ-PROMO-4220003 422 PROMO_RULE_COMPILE_FAILED Decision-graph rule failed to compile Fix the rule definition
EQ-PROMO-4220004 422 PROMO_NO_ACTIONS Promotion has no actions Add at least one action
EQ-PROMO-4220005 422 PROMO_UNKNOWN_FACT factsRequired references unknown fact Use a KNOWN_FACT (see §9)
EQ-PROMO-4220006 422 PROMO_PROTECTED_FIELD_CHANGE Changing an immutable field Don’t modify protected fields
EQ-PROMO-4220010 422 PROMO_INVALID_ACTION_FOR_OFFER_TYPE Action type not allowed for offerType Match action to offerType (§9)
EQ-PROMO-4220011 422 PROMO_INVALID_FORMULA_SYNTAX Formula has illegal tokens Use only price, digits, + - * / ( )
EQ-PROMO-4220012 422 PROMO_INVALID_DISCOUNT_TYPE discountType=4 without a formula action Add a formula action
EQ-PROMO-4220020 422 GROUP_INVALID_STATUS_TRANSITION Illegal group status change Use a valid transition
EQ-PROMO-4220021 422 GROUP_VALIDATION_FAILED Group validation failed Fix flagged issues
EQ-PROMO-4220022 422 GROUP_ASSIGN_NONEXISTENT_PROMOTIONS Assigning promotions that don’t exist Verify promotion ids
EQ-PROMO-4220030 422 PROMOCODE_INSUFFICIENT_PATTERN_SPACE Not enough unique codes for pattern Widen the pattern / reduce count
EQ-PROMO-4220031 422 PROMOCODE_TYPE_REQUIRED Missing promocode type Provide a PROMOCODE_TYPE
EQ-PROMO-4220032 422 PROMOCODE_TYPE_CONFIG_INVALID Bad typeConfig (N/M/X) Fix typeConfig for the type
EQ-PROMO-4220040 422 SCHEDULED_DRAFT_LIMIT_EXCEEDED Too many scheduled drafts Reduce scheduled drafts
EQ-PROMO-4220041 422 WORKFLOW_STATE_NOT_CONFIGURED State not in workflow config Configure the state
EQ-PROMO-4220042 422 WORKFLOW_ACTION_NOT_ALLOWED Action not allowed from current state Use an allowed action
EQ-PROMO-4220043 422 WORKFLOW_ENTITY_NOT_ENABLED Entity not in enabledWorkflowEntities Enable entity on the instance
EQ-PROMO-4220044 422 SCHEDULED_TIME_IN_PAST Scheduled time in the past Use a future time
EQ-PROMO-4220050 422 PROMOTION_LIST_NAME_ALREADY_EXISTS Duplicate list name Use a unique name
EQ-PROMO-4220051 422 PROMOCODE_INVALID_PROMOTION_ID Code references invalid promotion Verify promotionId
EQ-PROMO-4220052 422 INSTANCE_HAS_ACTIVE_PROMOTIONS Deleting an instance with active promos Remove/deactivate promos first

500 — Server

Code HTTP Constant When Resolution
EQ-PROMO-5000001 500 PROMO_EVAL_FAILED Rule evaluation threw at evaluation time Inspect the rule definition / logs
EQ-PROMO-5000099 500 PROMO_INTERNAL_SERVER_ERROR Unhandled server error Retry / check logs

Revision History
2026-08-05 | JP – Created the page and added the content.