Error Codes

Format

  • Marketplace codes: EQ-MKT- + a 7‑digit number whose first three digits encode the HTTP status (e.g. EQ-MKT-4040001 → 404). Some instance‑domain codes are reused from the User Service with the EQ-INS- prefix.
  • One outlier operational code is returned only on cold‑start init failure: EQ-MKT-5030001 (503, returned before the service is ready).

Error response shape

Every error response carries the fields below, plus an Error-Code response header. The HTTP status is derived from the code.

Field Description
errorCode The EQ-MKT- / EQ-INS- code
errorMessage Human‑readable, localized message (falls back to the raw code)
validations Optional array of field‑level messages
details Optional extension/validator details

errorMessage is localized, falling back to the raw code. When an external validator supplies human‑readable details, the first string overrides errorMessage.

HTTP‑status quick reference

HTTP Meaning Example codes
200 Informational success signal EQ-MKT-2000149 (provider failover occurred)
400 Bad request / missing/invalid input EQ-MKT-4000040, EQ-MKT-4000002, EQ-INS-4000035
401 Auth / API‑key failures EQ-MKT-4010108, EQ-MKT-4010158, EQ-MKT-4010094
403 Forbidden / not approved / not active EQ-MKT-4030033, EQ-MKT-4030095, EQ-MKT-4030163
404 Not found EQ-MKT-4040001, EQ-INS-4040001, EQ-MKT-4040085
409 Conflict / already exists EQ-MKT-4090004, EQ-MKT-4090160, EQ-MKT-4090104
410 Gone (deprecated/archived) EQ-MKT-4100008, EQ-MKT-4100050
422 Validation failed / semantic error EQ-MKT-4220005, EQ-MKT-4220048, EQ-MKT-4220117
500 Internal error / mutation failed EQ-MKT-5000037, EQ-MKT-5000060
502 Upstream app invocation failed EQ-MKT-5020141
503 Service/endpoint unavailable EQ-MKT-5030087, EQ-MKT-5030145, EQ-MKT-5030157
504 Timeout EQ-MKT-5040092

Instance errors (reused EQ-INS- prefix)

Code HTTP Constant When How to resolve
EQ-INS-4040001 404 INSTANCE_NOT_FOUND Instance id not found Verify the instance id
EQ-INS-4000035 400 INVALID_INSTANCE_ID Not a valid ObjectId Send a valid ObjectId
EQ-INS-4090002 409 INSTANCE_NAME_ALREADY_EXISTS Duplicate instance name Use a unique name
EQ-INS-5000031 500 INSTANCE_INTERNAL_SERVER_ERROR Unexpected instance error Retry / check logs
EQ-INS-4220003 422 INSTANCE_VALIDATION_FAILED Instance data invalid Fix validation errors
EQ-INS-4220007 422 INVALID_INSTANCE_NAME_FORMAT Bad name format Match required format
EQ-INS-4220006 422 INVALID_INSTANCE_STATUS Bad status value Use a valid status
EQ-INS-4000004 400 INSTANCE_ID_REQUIRED Missing instance id Provide instance id

(These support the not‑currently‑wired instance module; see §4.)

App registry & generic errors

Code HTTP Constant When How to resolve
EQ-MKT-4040001 404 APP_NOT_FOUND App id not found Verify appId
EQ-MKT-4000002 400 APP_ID_REQUIRED Missing app id Provide appId
EQ-MKT-4000003 400 INVALID_APP_ID Bad app id format Fix appId
EQ-MKT-4090004 409 APP_NAME_ALREADY_EXISTS Duplicate app name Use a unique name
EQ-MKT-4090039 409 APP_ALREADY_EXISTS Duplicate appId Use a new appId
EQ-MKT-4000040 400 INVALID_INPUT Input validation failed Fix the request body
EQ-MKT-5000041 500 INTERNAL_ERROR Internal error Retry / check logs
EQ-MKT-4220005 422 APP_VALIDATION_FAILED App data invalid Fix validation errors
EQ-MKT-4000006 400 APP_DATA_REQUIRED Empty body Send app data
EQ-MKT-4090007 409 APP_VERSION_ALREADY_EXISTS Version exists Bump the version
EQ-MKT-4100008 410 APP_DEPRECATED App deprecated Use a supported app/version
EQ-MKT-4000045 400 INVALID_PAGINATION Bad page/size Use valid pagination
EQ-MKT-4000038 400 INVALID_ID Bad id (generic) Send a valid id
EQ-MKT-4040036 404 ROUTE_NOT_FOUND Unknown route Check method + path
EQ-MKT-5000037 500 INTERNAL_SERVER_ERROR Unexpected error Retry / check logs
EQ-MKT-5000060 500 APP_UPDATE_FAILED Update returned no result Retry
EQ-MKT-5000061 500 APP_DELETE_FAILED Delete returned no result Retry

Approval workflow, versions, contracts, interfaces

Code HTTP Constant When How to resolve
EQ-MKT-4220048 422 INVALID_APP_STATUS_TRANSITION Illegal status transition Follow the transition map
EQ-MKT-4030049 403 APPROVAL_REQUIRED App not yet approved Approve first
EQ-MKT-4100050 410 APP_ARCHIVED App archived Use another app
EQ-MKT-4030051 403 APP_REJECTED App rejected Re‑submit after fixes
EQ-MKT-4030095 403 APP_NOT_APPROVED Enable attempted on non‑approved app Approve before enabling
EQ-MKT-4040056 404 APP_VERSION_NOT_FOUND Version not found Check version string
EQ-MKT-4220057 422 INVALID_VERSION_FORMAT Not SemVer Use SemVer
EQ-MKT-4220101 422 APP_VERSION_DEPRECATED Switching to a deprecated version Pick an active version
EQ-MKT-4090102 409 CANNOT_DEPRECATE_ACTIVE_VERSION Deprecating the active version Switch active version first
EQ-MKT-4040050 404 INTERFACE_NOT_FOUND Interface missing Register the interface
EQ-MKT-4090051 409 INTERFACE_ALREADY_EXISTS Duplicate interface id Use a new id
EQ-MKT-4090052 409 INTERFACE_NAME_VERSION_EXISTS Duplicate name+version Bump version
EQ-MKT-4220088 422 INTERFACE_VERSION_MISMATCH App doesn’t support interface/version Align versions
EQ-MKT-4040052 404 CONTRACT_NOT_FOUND Contract missing Register the contract
EQ-MKT-4090053 409 CONTRACT_ALREADY_EXISTS Duplicate contract Use a new id
EQ-MKT-4220054 422 CONTRACT_VALIDATION_FAILED App fails contract Implement required ops
EQ-MKT-4000055 400 CONTRACT_DATA_REQUIRED Empty contract body Send contract data
EQ-MKT-4220097 422 INVALID_CONTRACT Bad OpenAPI/JSON‑Schema Fix the contract doc

Config overrides, business/store, enablement

Code HTTP Constant When How to resolve
EQ-MKT-4040058 404 CONFIG_OVERRIDE_NOT_FOUND Override id missing Verify overrideId
EQ-MKT-4090059 409 CONFIG_OVERRIDE_ALREADY_EXISTS Duplicate override Patch existing instead
EQ-MKT-4220140 422 CONFIG_SCHEMA_VALIDATION_FAILED Settings violate configurationSchema Fix settings
EQ-MKT-4040009 / 4090010 / 4220011 / 4000012 404/409/422/400 APP_CONFIG_NOT_FOUND / _ALREADY_EXISTS / _VALIDATION_FAILED / _DATA_REQUIRED App config CRUD problems Adjust config request
EQ-MKT-4030013 403 APP_NOT_ENABLED_FOR_BUSINESS Configuring a non‑enabled app Enable at business level first
EQ-MKT-4000014 / 4000015 / 4040016 400/400/404 BUSINESS_ID_REQUIRED / INVALID_BUSINESS_ID / BUSINESS_NOT_FOUND Business scoping issues Provide a valid businessId
EQ-MKT-4090017 409 APP_ALREADY_ENABLED_FOR_BUSINESS Re‑enabling No action needed
EQ-MKT-4040018 404 APP_NOT_ENABLED_FOR_BUSINESS_DISABLE Disabling a non‑enabled app Nothing to disable
EQ-MKT-4000019 / 4000020 / 4040021 400/400/404 STORE_ID_REQUIRED / INVALID_STORE_ID / STORE_NOT_FOUND Store scoping issues Provide a valid storeId
EQ-MKT-4090084 409 APP_ALREADY_ENABLED App already enabled for store+interface No action needed
EQ-MKT-4040085 404 ENABLEMENT_NOT_FOUND Enablement record missing Enable first
EQ-MKT-4000086 400 ROLLBACK_NOT_AVAILABLE No previous version Nothing to roll back to
EQ-MKT-4090104 409 APP_HAS_ACTIVE_ENABLEMENTS Deleting an app still enabled Disable everywhere first
EQ-MKT-4220103 422 DEPENDENCY_NOT_ENABLED Required dependency app not enabled Enable the dependency
EQ-MKT-4040105 404 AUDIT_ENTRY_NOT_FOUND Audit entry missing Check the entry id

Authorization & authentication

Code HTTP Constant When How to resolve
EQ-MKT-4010108 401 AUTHENTICATION_REQUIRED Missing/invalid JWT Send a valid bearer token
EQ-MKT-4030033 403 UNAUTHORIZED_APP_ACCESS Lacking privilege / not admin Grant privilege
EQ-MKT-4030034 403 UNAUTHORIZED_BUSINESS_ACCESS No access to business Grant access
EQ-MKT-4030035 403 UNAUTHORIZED_STORE_ACCESS No access to store Grant access
EQ-MKT-4010158 401 API_KEY_INVALID Bad/unknown/revoked API key Issue a new key
EQ-MKT-4010159 401 API_KEY_EXPIRED Key past expiry Rotate the key
EQ-MKT-4030163 403 APP_NOT_ACTIVE Owning app deprecated/archived/rejected/deleted Reactivate the app
EQ-MKT-4220162 422 API_KEY_LIMIT_REACHED >5 active keys Revoke an old key
EQ-MKT-4090160 409 APP_SELF_REGISTER_CONFLICT appId+version already registered Bump version
EQ-MKT-4010094 401 HMAC_SIGNATURE_INVALID HMAC verify failed Fix signing secret

Connector artifact / deployment

Code HTTP Constant When
EQ-MKT-4000030 / 4220031 400/422 LAMBDA_ARN_REQUIRED / INVALID_LAMBDA_ARN Lambda deployment missing/invalid ARN
EQ-MKT-4000032 400 NPM_PACKAGE_REQUIRED Bundled deployment missing npm package
EQ-MKT-4000062 400 APP_NOT_BUNDLED_TYPE Operation needs bundled type
EQ-MKT-4040063 404 CONNECTOR_ARTIFACT_NOT_FOUND No connector artifact on app
EQ-MKT-4000064 400 NPM_PACKAGE_OR_CONNECTOR_ARTIFACT_REQUIRED Bundled needs npm or artifact
EQ-MKT-4000065 400 BASE_URL_REQUIRED External deployment needs baseUrl
EQ-MKT-4000066–4000068 400 CONNECTOR_ARTIFACT_*_REQUIRED packageName/version/registryUrl missing
EQ-MKT-4220069–4220072 422 CONNECTOR_ARTIFACT_*_INVALID deploymentType/semver/packageName/registryUrl invalid
EQ-MKT-4000073 400 CONNECTOR_ARTIFACT_DOWNLOAD_URL_REQUIRED_FOR_EXTERNAL External artifact missing downloadUrl
EQ-MKT-4040098 / 4220100 404/422 CONNECTOR_CLASS_NOT_FOUND / INVALID_CONNECTOR_CLASS_FORMAT Bundled connector class load/format
EQ-MKT-4000099 400 INVOCATION_TARGET_REQUIRED External app missing invocationTarget
EQ-MKT-5000080 500 LAMBDA_CLIENT_NOT_CONFIGURED Missing AWS_REGION for Lambda client
EQ-MKT-4000081 400 UNSUPPORTED_DEPLOYMENT_TYPE Provisioning can’t handle type

Payment configuration & multi‑provider routing

Code HTTP Constant When
EQ-MKT-4220110 422 PAYMENT_CONTRACT_MISSING_OPERATIONS Payment contract ops missing
EQ-MKT-4000111 400 INVALID_PAYMENT_OPERATION Bad operation name
EQ-MKT-4000112–4000115 400 PROVIDER_TYPE / MERCHANT_ID / API_KEY / API_SECRET _REQUIRED Missing payment fields
EQ-MKT-4220116 422 INVALID_CURRENCY_CODE Bad ISO‑4217 currency
EQ-MKT-4220117 422 APP_NOT_PAYMENT_CAPABLE App lacks PAYMENT capability
EQ-MKT-4040118 404 APP_NOT_ENABLED_FOR_STORE App not enabled for store
EQ-MKT-4220119 / 4220120 422 PRIMARY_PROVIDER_REQUIRED / MULTIPLE_PRIMARY_PROVIDERS Exactly one primary required
EQ-MKT-4220121 / 4220122 422 DUPLICATE_PROVIDER_PRIORITY / DUPLICATE_PROVIDER_TYPE Duplicate priority/type
EQ-MKT-4220123 / 4220124 422 WEIGHTED_SHARES_REQUIRED / _INVALID_SUM Weighted routing shares
EQ-MKT-4000125 400 DEFAULT_PROVIDER_NOT_FOUND Default provider not in list
EQ-MKT-4040144 404 NO_PROVIDER_FOR_PAYMENT_TYPE No provider for type
EQ-MKT-5030145 503 ALL_PROVIDERS_UNAVAILABLE All circuits open/disabled
EQ-MKT-4040146 404 PROVIDER_NOT_FOUND_IN_CONFIG Provider not in config
EQ-MKT-4220147 422 CANNOT_DISABLE_ALL_PROVIDERS Must keep ≥1 enabled
EQ-MKT-4040148 404 MULTI_PROVIDER_CONFIG_NOT_FOUND No multi‑provider config
EQ-MKT-2000149 200 PROVIDER_FAILOVER_OCCURRED Processed via secondary (info)
EQ-MKT-4040150 404 PAYMENT_CONFIG_NOT_FOUND No payment config for store
EQ-MKT-4220151 422 PAYMENT_CONFIG_REQUIRED_FOR_ENABLE Configure payment before enable
EQ-MKT-4220152 422 APP_DRAINING App draining; new txns rejected
EQ-MKT-4220153 422 PAYMENT_CONFIG_VALIDATION_ERRORS Multiple payment validation errors

Notification configuration

Code HTTP Constant When
EQ-MKT-4040126 404 NOTIFICATION_APP_NOT_ENABLED Notification app not enabled for store
EQ-MKT-4220127 422 NOTIFICATION_CONFIG_NOT_INITIALIZED Enable the app first
EQ-MKT-4040128 / 4090129 404/409 NOTIFICATION_EVENT_NOT_FOUND / _DUPLICATE_NAME Event lookup/duplicate
EQ-MKT-4000130 / 4000143 400 NOTIFICATION_EVENT_NAME_REQUIRED / _NAME_LENGTH Event name missing / length 2–255
EQ-MKT-4000131 / 4000132 400 NOTIFICATION_EVENT_INVALID_STATUS / _INVALID_DOMAIN Bad status/domain
EQ-MKT-4040133 / 4090134 404/409 NOTIFICATION_ACTION_NOT_FOUND / _DUPLICATE_NAME Action lookup/duplicate
EQ-MKT-4000135–4000137 400 NOTIFICATION_ACTION_NAME / _CHANNEL / _TEMPLATE Missing/invalid action fields
EQ-MKT-4040138 / 4000139 404/400 NOTIFICATION_ACTION_EVENT_NOT_FOUND / _INVALID_STATUS Action references bad event/status

App invocation, health, webhooks, service map

Code HTTP Constant When
EQ-MKT-5020141 502 APP_INVOCATION_FAILED External app invocation failed
EQ-MKT-4220142 422 APP_HMAC_SECRET_MISSING External app HMAC secret not set
EQ-MKT-5030087 503 ENDPOINT_UNREACHABLE External endpoint health check failed
EQ-MKT-5030089 503 DEFAULT_APP_UNAVAILABLE Default app failover exhausted
EQ-MKT-5030157 503 APP_HEALTH_CHECK_FAILED Health check failed
EQ-MKT-5000090 500 EVENT_SYNC_FAILED Event delivery to service failed
EQ-MKT-4220091 422 EXTENSION_VALIDATION_FAILED Pre‑enablement webhook validation failed
EQ-MKT-5040092 504 WEBHOOK_TIMEOUT Validation webhook timed out
EQ-MKT-4220093 422 INVALID_WEBHOOK_RESPONSE Webhook returned bad format
EQ-MKT-4040082 / 5000083 404/500 WEBHOOK_NOT_FOUND / WEBHOOK_UPDATE_FAILED Webhook lookup/update
EQ-MKT-4090105 409 WEBHOOK_HAS_PENDING_DELIVERIES Can’t delete with pending deliveries
EQ-MKT-5030106 503 WEBHOOK_URL_UNREACHABLE Callback URL unreachable
EQ-MKT-4000107 400 INVALID_EVENT_TYPES Bad webhook event types
EQ-MKT-4220096 422 APP_REGISTRATION_FAILED Contract/health check on registration
EQ-MKT-4220020 / 4220021 / 4220022 422 SERVICE_INSTANCE_MAP_INVALID_SERVICE / _INVALID_OBJECTID / _REQUIRED serviceInstanceMap validation
EQ-MKT-4000046 / 4000047 400 SECURITY_INVALID_CONTENT_LENGTH / SECURITY_PROTOCOL_UPGRADE_NOT_ALLOWED Request‑smuggling guards

(App‑config / contract / interface mutation failures EQ-MKT-5000074–5000079 all map to HTTP 500.)

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