Error Codes

Every error has a stable code, a fixed HTTP status, and a localized message. Below is a representative subset per category.

Format & response shape

  • Format: EQ-ACC-{httpStatus}{sequence}, e.g. EQ-ACC-4040024 = HTTP 404, sequence 0024. The 3-digit HTTP status is embedded in the code itself.
  • Every error response returns the error code, a localized message, and the numeric HTTP status.

HTTP status quick reference

Code family Meaning
EQ-ACC-400xxxx 400 Bad Request (malformed input, missing ids)
EQ-ACC-401xxxx (via 423-series enum) see auth codes below
EQ-ACC-403xxxx 403 Forbidden (insufficient permission, inactive instance)
EQ-ACC-404xxxx 404 Not Found
EQ-ACC-409xxxx 409 Conflict (duplicates, in-use, overlaps)
EQ-ACC-422xxxx 422 Unprocessable (validation / business-rule failures)
EQ-ACC-423xxxx Auth/JWT codes (map to 401/403, see ERROR_STATUS_CODES)
EQ-ACC-500xxxx 500 internal errors (and non-fatal log codes)
EQ-ACC-502xxxx 502 upstream integration failures (registration)

Common / generic

Code HTTP Constant When How to resolve
EQ-ACC-4000001 400 INVALID_ID ObjectId param is malformed Send a valid 24-hex Mongo id
EQ-ACC-4000004 400 INVALID_REQUEST_BODY_FORMAT Body is not valid JSON Fix JSON payload
EQ-ACC-4000005 400 INVALID_REQUEST_FIELDS Unknown field in body Remove unrecognized fields
EQ-ACC-4220003 422 INVALID_PAGINATION page/limit out of range Use valid pagination values
EQ-ACC-4040010 404 ROUTE_NOT_FOUND No matching route Check method + path
EQ-ACC-4030074 403 AUTH_INSUFFICIENT_PERMISSIONS Required privilege not granted Grant the required account:* privilege

Instance & attribute

Code HTTP Constant When How to resolve
EQ-ACC-4040011 404 INSTANCE_NOT_FOUND instanceId not found Use a valid instance
EQ-ACC-4090012 409 INSTANCE_NAME_ALREADY_EXISTS Duplicate instance name Choose another name
EQ-ACC-4030075 403 INSTANCE_INACTIVE Instance is INACTIVE Reactivate instance or use active one
EQ-ACC-4090021 409 DUPLICATE_ATTRIBUTE_KEY Attribute key exists Use a unique key

Account domain (entities)

Code HTTP Constant When How to resolve
EQ-ACC-4040024 404 ACCOUNT_NOT_FOUND Account id not found Verify accountId/instanceId
EQ-ACC-4090025 409 ACCOUNT_ALREADY_EXISTS Duplicate account name in instance Use another name
EQ-ACC-4000026 400 INVALID_PARENT_ACCOUNT parentAccountId invalid/other instance Use a valid parent in same instance
EQ-ACC-4090033 409 CIRCULAR_HIERARCHY_DETECTED Reparenting would create a cycle Choose a non-descendant parent
EQ-ACC-4040031 404 ACCOUNT_USER_NOT_FOUND Account-user link absent Verify user link
EQ-ACC-4090037 409 COST_CENTRE_ALREADY_EXISTS Duplicate cost-centre name Rename
EQ-ACC-4090079 409 COST_CENTRE_IN_USE_BY_TEAM Cost centre linked to team(s) Unlink teams first
EQ-ACC-4040040 404 CONTRACT_NOT_FOUND Contract absent Verify contractId
EQ-ACC-4090076 409 PAYMENT_ALREADY_EXISTS Duplicate paymentMethodId Use a new payment-method id

Validation (422) & PO order validation

Code HTTP Constant When How to resolve
EQ-ACC-4220049 422 ACCOUNT_VALIDATION_FAILED Account payload fails domain validation Fix fields per schema
EQ-ACC-4090059 409 CONTRACT_DATE_OVERLAP Overlapping contract period Adjust contract dates
EQ-ACC-4220091 422 NO_ACTIVE_CONTRACT No active/in-window contract Ensure an ACTIVE contract exists
EQ-ACC-4220092 422 NO_ACTIVE_BUDGET No active budget for cost centre Create/activate a budget
EQ-ACC-4220093 422 BUDGET_EXCEEDED orderAmount + spent > budget amount Increase budget or reduce order
EQ-ACC-4220094 422 CREDIT_LIMIT_EXCEEDED PO order over contract credit limit Raise credit limit or lower order
EQ-ACC-4000095 400 PO_NUMBER_REQUIRED PURCHASE_ORDER without purchaseOrderNumber Supply a PO number

Budget-transaction idempotency

Code HTTP Constant When How to resolve
EQ-ACC-4090081 409 BUDGET_DEBIT_AMOUNT_MISMATCH DEBIT retry for same orderId with different amount Reconcile the order amount
EQ-ACC-4220077 422 BUDGET_CREDIT_WITHOUT_DEBIT CREDIT for an orderId with no prior DEBIT Ensure a DEBIT exists first

Account action (invite/membership)

Code HTTP Constant When
EQ-ACC-4220089 422 USER_INVITE_FAILED User-service invite/lookup failed
EQ-ACC-4090090 409 TEAM_MEMBER_ALREADY_EXISTS User already on the team
EQ-ACC-4090091 409 BUYER_ALREADY_EXISTS Email already a buyer of the account

Authentication / Authorization (423-series enum)

AUTH_MISSING_TOKEN, AUTH_INVALID_TOKEN, AUTH_TOKEN_EXPIRED, AUTH_INVALID_SIGNATURE, AUTH_INVALID_ISSUER, AUTH_INVALID_AUDIENCE, AUTH_FORBIDDEN, plus test-token codes — coded EQ-ACC-4230001…EQ-ACC-4230015, mapped to 401 (or 403 for AUTH_FORBIDDEN) by ERROR_STATUS_CODES.

Self-registration (0075–0087) & admin-invite log codes (0088–0089)

Code HTTP Constant When
EQ-ACC-4040075 404 REGISTER_STORE_NOT_FOUND storeId matches no active store
EQ-ACC-4220076 422 REGISTER_INELIGIBLE_STORE_TYPE Store type does not support B2B registration
EQ-ACC-4090077 409 REGISTER_COMPANY_ALREADY_EXISTS Account name already taken
EQ-ACC-5000081 500 REGISTER_USER_CREATE_FAILED User service errored during registration
EQ-ACC-5020086 502 REGISTER_FOUNDATION_INTEGRATION_FAILED Foundation integration call failed
EQ-ACC-5020087 502 REGISTER_USER_INTEGRATION_FAILED User integration call failed
EQ-ACC-5000088 (log only) ADMIN_REGISTER_INVITE_EMAIL_FAILED Invite email failed; 201 still returned
EQ-ACC-5000089 (log only) ADMIN_REGISTER_INVITE_PARAM_MISSING activationParam missing; 201 still returned

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