Foundation Service — Error Codes

Platform: Infosys Equinox | Format: EQ-FND-<httpStatus><4digits>

Source of truth: all error codes are defined in the ErrorCodes enum in src/ErrorCode.ts (200+ codes), with an HTTP-status map at the bottom of that file. This document explains the most commonly encountered codes with resolution guidance, plus a representative sample of every category. For an exhaustive list, refer to src/ErrorCode.ts.

Error Code Format

EQ-FND-<httpStatus><4digits>
  • EQ — Equinox platform prefix
  • FND — Foundation service identifier
  • <httpStatus> — The 3-digit HTTP status code this error maps to (400, 401, 403, 404, 409, 413, 422, 429, 500)
  • <4digits> — A unique 4-digit code identifying the specific error within that HTTP status

Error Response Shape

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "INVALID_STORE_LOCALE",
  "errorCode": "EQ-FND-4220105"
}

Use errorCode for machine-matching in error handlers. Use message for display or logging.

HTTP Status Code Quick Reference

HTTP Status What it means in this service
400 Bad Request Malformed request, missing required field, wrong type, or invalid format (e.g. INVALID_FLAG_KEY_FORMAT, INVALID_ID). Fix the request shape before retrying.
401 Unauthorized Missing/expired/invalid JWT (e.g. AUTH_TOKEN_MISSING, AUTH_TOKEN_EXPIRED, AUTH_TOKEN_INVALID_ISSUER). Refresh the Cognito token and retry.
403 Forbidden Valid token but missing privilege (FORBIDDEN). Ask an admin to grant the correct role.
404 Not Found The referenced entity does not exist or was soft-deleted. Verify the ID.
409 Conflict Uniqueness or referential conflict (duplicate name/ID, deleting a store with children).
413 Payload Too Large Uploaded batch file exceeds the allowed size (FILE_TOO_LARGE).
422 Unprocessable Entity Valid JSON but values fail business-rule validation (bad locale, circular hierarchy, invalid status).
429 Too Many Requests Concurrency limit hit (e.g. MAX_CONCURRENT_JOBS_REACHED).
500 Internal Server Error Server-side failure — AWS service call, database, or cache error. Check logs and AWS/IAM config.

Business Errors

Code HTTP Constant When does this happen How to resolve
EQ-FND-4040001 404 BUSINESS_NOT_FOUND The businessId in the URL does not exist. Verify the ID with GET /v1/businesses.
EQ-FND-4090002 409 BUSINESS_NAME_ALREADY_EXISTS A POST used a name already taken in the instance. Choose a unique name.
EQ-FND-4090003 409 BUSINESS_ID_ALREADY_EXISTS An explicit businessId is already in use. Omit businessId to auto-generate, or use a different value.
EQ-FND-4220004 422 INVALID_BUSINESS_NAME_FORMAT The name has disallowed characters (only letters, digits, spaces, hyphens allowed). Remove special characters.
EQ-FND-4220005 422 INVALID_BUSINESS_STATUS status is not 1 (Active) or 0 (Inactive). Use 1 or 0.
EQ-FND-4220006 422 INVALID_BUSINESS_CDN_URL The cdnUrl field is not a valid URL. Provide a valid https:// URL.
EQ-FND-4220007 422 INVALID_BUSINESS_STORAGE_URL The storageServiceUrl field is not a valid URL. Provide a valid https:// URL.
EQ-FND-4220008 422 INVALID_BUSINESS_DEFAULT_LOCALE defaultLocale is not in the locales master data. Use a value from GET /v1/locales.
EQ-FND-4220009 422 INVALID_BUSINESS_DEFAULT_CURRENCY defaultCurrency is not in the currencies master data. Use a value from GET /v1/currencies.
EQ-FND-4040010 404 BUSINESS_PROPERTY_NOT_FOUND A property key does not exist on the business. Fetch the business and inspect properties; use PUT to add.
EQ-FND-4220011 422 INVALID_BUSINESS_PROPERTY_NAME Property name failed validation. Use a valid property key.
EQ-FND-4220012 422 INVALID_BUSINESS_PROPERTY_VALUE Property value failed validation. Provide a valid value.

Store Errors

Code HTTP Constant When does this happen How to resolve
EQ-FND-4040100 404 STORE_NOT_FOUND The storeId does not exist in this instance. Verify with GET /v1/stores; confirm the instance.
EQ-FND-4090101 409 STORE_NAME_ALREADY_EXISTS A name already taken in the instance. Use a unique name.
EQ-FND-4090102 409 STORE_ID_ALREADY_EXISTS An explicit storeId is already in use. Omit storeId or use a different value.
EQ-FND-4220103 422 INVALID_STORE_TYPE type not in store_types master data. Use a value from GET /v1/store-types.
EQ-FND-4220104 422 INVALID_STORE_STATUS status not 1 or 0. Use 1 or 0.
EQ-FND-4220105 422 INVALID_STORE_LOCALE locale/defaultLocale not in master data. Use a value from GET /v1/locales.
EQ-FND-4220106 422 INVALID_STORE_CURRENCY currency/defaultCurrency not in master data. Use a value from GET /v1/currencies.
EQ-FND-4220107 422 INVALID_STORE_TIMEZONE timeZone not in timezones master data. Use a value from GET /v1/timezones.
EQ-FND-4040108 404 STORE_PROPERTY_NOT_FOUND A property key does not exist on the store. Fetch the store and inspect properties.
EQ-FND-4040109 404 STORE_BUSINESS_NOT_FOUND The referenced businessId does not exist. Create the business first.
EQ-FND-4220110 422 INVALID_STORE_ID_FORMAT storeId format is invalid. Provide a valid numeric ID.
EQ-FND-4220111 422 INVALID_STORE_NAME_FORMAT name format is invalid. Use allowed characters.
EQ-FND-4220112 422 INVALID_STORE_URL_FORMAT A store URL field is malformed. Provide a valid URL.
EQ-FND-4220122 422 INVALID_STORE_JURISDICTIONS_FORMAT The jurisdictions field is malformed. Correct the field structure.
EQ-FND-4220123 422 INVALID_BUSINESS_ID_FORMAT businessId format is invalid. Provide a valid numeric ID.
EQ-FND-4220124 422 STORE_VALIDATION_FAILED A custom store validator extension rejected the payload (see Extension & Lifecycle Framework – Foundation – Infosys Equinox Developer Portal). Response details/extensionDetails carry the extension’s errors. Fix the payload per the returned extension errors.

Store Hierarchy Errors

Code HTTP Constant When does this happen How to resolve
EQ-FND-4220999 422 CIRCULAR_HIERARCHY_DETECTED A parent change would create a cycle. Choose a parent not already a descendant.
EQ-FND-4220998 422 MAX_HIERARCHY_DEPTH_EXCEEDED Placement would exceed level 3. Flatten the hierarchy.
EQ-FND-4040997 404 PARENT_STORE_NOT_FOUND parentStoreId does not exist. Create the parent first.
EQ-FND-4220996 422 STORE_CANNOT_BE_OWN_PARENT parentStoreId equals the store’s own ID. Use a different parent, or null.
EQ-FND-4090995 409 CANNOT_DELETE_STORE_WITH_CHILDREN The store has children. Delete/re-parent children first.

Site Errors

Code HTTP Constant When does this happen
EQ-FND-4040200 404 SITE_NOT_FOUND The siteId does not exist.
EQ-FND-4090201 409 SITE_NAME_ALREADY_EXISTS Site name already taken in the instance.
EQ-FND-4090202 409 SITE_ID_ALREADY_EXISTS Explicit siteId already in use.
EQ-FND-4220203 422 INVALID_SITE_DOMAIN domain is not a valid hostname (no protocol/path).
EQ-FND-4220204 422 INVALID_SITE_STATUS status not 1 or 0.
EQ-FND-4090208 409 DUPLICATE_SITE_DOMAIN Another site already uses this domain.
EQ-FND-5000209 500 SITE_UPDATE_FAILED Persistence error updating the site.
EQ-FND-5000210 500 SITE_DELETE_FAILED Persistence error deleting the site.

The Sites domain is currently not registered at runtime (see API Endpoints – Foundation – Infosys Equinox Developer Portal); these codes apply once it is enabled.

Seller Errors

Code HTTP Constant When does this happen
EQ-FND-4040300 404 SELLER_NOT_FOUND The sellerId does not exist.
EQ-FND-4090301 409 SELLER_ID_ALREADY_EXISTS Explicit sellerId already in use.
EQ-FND-4220302 422 INVALID_SELLER_EMAIL email fails RFC 5322 validation.
EQ-FND-4220303 422 INVALID_SELLER_PHONE phone fails E.164 validation.
EQ-FND-4040304 404 SELLER_STORE_NOT_FOUND The referenced storeId does not exist.
EQ-FND-4220309 422 INVALID_SELLER_STATUS status not 1 or 0.
EQ-FND-5000311 500 SELLER_UPDATE_FAILED Persistence error updating the seller.

The Sellers domain is currently not registered at runtime; these codes apply once it is enabled.

Association Errors (Store / Site-Data / Sitedata-Service)

Code (range) HTTP Examples Notes
EQ-FND-4040500 404 STORE_ASSOCIATION_NOT_FOUND Store association not found.
EQ-FND-4220502–4220508 422 store-association validation errors Field/rule validation.
EQ-FND-5000509–5000513 500 store-association persistence errors DB failures.
EQ-FND-4040400 404 SITE_DATA_NOT_FOUND Site data record not found.
EQ-FND-4040403 404 SITE_DATA_ASSOCIATION_NOT_FOUND Site-data association not found.
EQ-FND-5000419 500 SITEDATA_SERVICE_ASSOCIATION_DELETE_FAILED Delete failed.

Feature Flag Errors

Code HTTP Constant When does this happen
EQ-FND-4040620 404 FEATURE_FLAG_NOT_FOUND The flag id/key does not exist.
EQ-FND-4090620 409 DUPLICATE_FLAG_KEY A flag with the same key already exists.
EQ-FND-4000620 400 INVALID_FLAG_KEY_FORMAT The flag key format is invalid.
EQ-FND-5000620 500 FLAG_EVALUATION_FAILED Rule evaluation threw an error.

Master Data Errors

Code HTTP Constant
EQ-FND-4040700 404 CURRENCY_NOT_FOUND
EQ-FND-4040601 404 LOCALE_NOT_FOUND
EQ-FND-4040602 404 TIMEZONE_NOT_FOUND
EQ-FND-4040603 404 COUNTRY_NOT_FOUND
EQ-FND-4040605 404 STORE_TYPE_NOT_FOUND

Location & Location Event Errors (sample)

The location domain defines ~40 codes (ErrorCode.ts ~2146–2228). Common ones:

Code HTTP Constant
EQ-FND-4040720 404 LOCATION_NOT_FOUND
EQ-FND-4220726 422 INVALID_LOCATION_GEO
EQ-FND-4220752 422 GEO_COORDINATES_INVALID
EQ-FND-4040740 404 LOCATION_EVENT_NOT_FOUND

Batch / Job / Schedule / Execution Errors (sample)

The batch domain defines ~40 codes (ErrorCode.ts ~1524–2049). Common ones:

Code HTTP Constant Notes
EQ-FND-4040800 404 BATCH_NOT_FOUND Batch/job/schedule not found.
EQ-FND-4000818 400 INVALID_CRON_EXPRESSION Schedule cron syntax invalid.
EQ-FND-4220822 422 BATCH_ERROR_THRESHOLD_EXCEEDED Too many failed records in a run.
EQ-FND-4290042 429 MAX_CONCURRENT_JOBS_REACHED Concurrency cap hit.
EQ-FND-5000820 500 LAMBDA_INVOCATION_FAILED The processing Lambda could not be invoked.
EQ-FND-5000821 500 EVENTBRIDGE_RULE_CREATION_FAILED EventBridge PutRule failed for a SCHEDULED schedule (see below).

File Upload Errors

Code HTTP Constant
EQ-FND-4040900 404 FILE_UPLOAD_NOT_FOUND
EQ-FND-4130901 413 FILE_TOO_LARGE
EQ-FND-4220902 422 INVALID_FILE_TYPE

Generic / Auth / Infrastructure Errors

Code HTTP Constant When does this happen How to resolve
EQ-FND-4000700 400 INVALID_ID A path/body ID is malformed. Provide a valid ID.
EQ-FND-4010001 401 AUTH_TOKEN_MISSING No Authorization header. Send a Bearer token.
EQ-FND-4010004 401 AUTH_TOKEN_EXPIRED The JWT has expired. Refresh the token.
EQ-FND-4010013 401 AUTH_TOKEN_INVALID_ISSUER Token issuer not in the allowlist. Use a token from a trusted Cognito pool.
EQ-FND-4010900 401 UNAUTHORIZED Authentication failed. Re-authenticate.
EQ-FND-4030901 403 FORBIDDEN Missing required privilege. Request the needed role.
EQ-FND-5000800 500 DATABASE_ERROR A MongoDB operation failed. Check DB connectivity and logs.
EQ-FND-5000801 500 CACHE_ERROR A Redis operation failed. Check Redis connectivity (service falls back to DB).
EQ-FND-5000802 500 EVENT_PUBLISH_ERROR Publishing a domain event to EventBridge failed. Verify AWS credentials/IAM events:PutEvents and EVENT_BUS_NAME.
EQ-FND-5000821 500 EVENTBRIDGE_RULE_CREATION_FAILED Creating a SCHEDULED batch schedule’s EventBridge cron rule failed. Validate the cron expression; check IAM events:PutRule/PutTargets; confirm AWS_REGION.

Note: older documentation referenced EQ-FND-5000332 / EVENT_PUBLISH_FAILED. That code does not exist — the correct one is EQ-FND-5000802 / EVENT_PUBLISH_ERROR shown above.


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