Spidr Error Codes

This document provides comprehensive information about all possible error responses in the Spidr Unified API, organized by endpoint.

Error Response Structure
User Endpoints
Account Endpoints
ACH Account Endpoints
Card Endpoints
Transaction Endpoints
Common Errors

Error Response Structure

All error responses follow this standard format:

{
  "status": "error",
  "error": {
    "errorType": "INPUT_ERROR",
    "errorCode": "ERROR_CODE_HERE",
    "message": "Human-readable error message",
    "errorData": {
      "additional": "contextual data (optional)"
    }
  }
}

Error Types

The API uses specific error types to categorize errors:

INVALID_REQUEST: Request validation errors (duplicate IDs, malformed requests)
INVALID_INPUT: Input validation errors (invalid data, ineligible statuses)
NOT_FOUND: Resource not found errors
USER_ERROR: User-specific errors (anonymous user restrictions, CIP status issues)
ACCOUNT_ERROR: Account-specific errors (insufficient balance, creation failures)
CARD_ERROR: Card-specific errors (update/create failures)
INPUT_ERROR: General input validation errors (eligibility, status checks)
LOOKUP_ERROR: Database/system lookup failures (500-level errors)
ZTM_ERROR: Zero Touch Monitoring workflow errors

User Endpoints

Create User (`POST /user/create`)

Error Code	HTTP Status	Description	Example Payload
`DEFAULT_PRODUCT_NOT_FOUND`	404	No default product found for the company	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "DEFAULT_PRODUCT_NOT_FOUND", "message": "Default product not found."}}`
`DUPLICATE_CLIENT_USER_IDNUMBER`	400	A user with this ID number already exists	`{"status": "error", "error": {"errorType": "INVALID_REQUEST", "errorCode": "DUPLICATE_CLIENT_USER_IDNUMBER", "message": "Duplicate user by idNumber."}}`
`DUPLICATE_CLIENT_USER_ID`	400	A user with this client user ID already exists	`{"status": "error", "error": {"errorType": "INVALID_REQUEST", "errorCode": "DUPLICATE_CLIENT_USER_ID", "message": "Duplicate clientUserId: CLIENT_123.", "errorData": {"clientUserId": "CLIENT_123"}}}`
`IDV_TEMPLATE_NOT_FOUND`	404	The specified IDV template was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "IDV_TEMPLATE_NOT_FOUND", "message": "IDV template not found."}}`
`INVALID_USER_IDNUMBER`	400	The provided ID number is invalid	`{"status": "error", "error": {"errorType": "INVALID_REQUEST", "errorCode": "INVALID_USER_IDNUMBER", "message": "Invalid Id Number"}}`

Edit User (`PATCH /user/edit`)

Error Code	HTTP Status	Description	Example Payload
`NOT_ALLOWED_FOR_ANONYMOUS_USER`	400	This action cannot be performed on anonymous users	`{"status": "error", "error": {"errorType": "USER_ERROR", "errorCode": "NOT_ALLOWED_FOR_ANONYMOUS_USER", "message": "Action not allowed for anonymous user."}}`
`USER_NOT_FOUND`	404	The specified user was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "USER_NOT_FOUND", "message": "Active user not found."}}`
`USER_LOOKUP_ERROR`	500	Error occurred while looking up the user	`{"status": "error", "error": {"errorType": "LOOKUP_ERROR", "errorCode": "USER_LOOKUP_ERROR", "message": "User lookup failed."}}`

Edit ID Number (`PATCH /user/edit-id-number`)

Error Code	HTTP Status	Description	Example Payload
`NOT_ALLOWED_FOR_ANONYMOUS_USER`	400	This action cannot be performed on anonymous users	`{"status": "error", "error": {"errorType": "USER_ERROR", "errorCode": "NOT_ALLOWED_FOR_ANONYMOUS_USER", "message": "Action not allowed for anonymous user."}}`
`USER_NOTHING_TO_MODIFY`	400	No changes detected in the update request	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "USER_NOTHING_TO_MODIFY", "message": "Nothing to modify for user"}}`
`DUPLICATE_CLIENT_USER_IDNUMBER`	400	A user with this ID number already exists	`{"status": "error", "error": {"errorType": "INVALID_REQUEST", "errorCode": "DUPLICATE_CLIENT_USER_IDNUMBER", "message": "Duplicate user by idNumber."}}`
`UNSUPPORTED_ID_TYPE`	400	The ID type is not supported for this vendor	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "UNSUPPORTED_ID_TYPE", "message": "The provided idType is not supported"}}`
`INVALID_USER_IDNUMBER`	400	The provided ID number is invalid	`{"status": "error", "error": {"errorType": "INVALID_REQUEST", "errorCode": "INVALID_USER_IDNUMBER", "message": "Invalid Id Number"}}`

Update User CIP Status (`PATCH /user/update-cip-status`)

Error Code	HTTP Status	Description	Example Payload
`NOT_ALLOWED_FOR_ANONYMOUS_USER`	400	This action cannot be performed on anonymous users	`{"status": "error", "error": {"errorType": "USER_ERROR", "errorCode": "NOT_ALLOWED_FOR_ANONYMOUS_USER", "message": "Action not allowed for anonymous user."}}`
`NOT_ALLOWED_FOR_CIP_STATUS`	400	User's current CIP status does not allow this update	`{"status": "error", "error": {"errorType": "USER_ERROR", "errorCode": "NOT_ALLOWED_FOR_CIP_STATUS", "message": "Action not allowed for user with CIP status: pend."}}`
`CIP_STATUS_NOT_ELIGIBLE_FOR_UPDATE`	400	CIP status cannot be updated (>30 days since decision)	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "CIP_STATUS_NOT_ELIGIBLE_FOR_UPDATE", "message": "The user's CIP status is not eligible to be updated."}}`
`USER_NOTHING_TO_MODIFY`	400	No changes detected (CIP status is already the requested value)	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "USER_NOTHING_TO_MODIFY", "message": "Nothing to modify for user"}}`

Archive User (`PATCH /user/archive`)

Error Code	HTTP Status	Description	Example Payload
`USER_ARCHIVE_ACTIVE_ACCOUNTS_EXIST`	400	Cannot archive user with active accounts	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "USER_ARCHIVE_ACTIVE_ACCOUNTS_EXIST", "message": "User has active accounts and cannot be archived."}}`
`USER_NOT_FOUND`	404	The specified user was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "USER_NOT_FOUND", "message": "Active user not found."}}`

Retrieve ID Number (`GET /user/retrieve-id-number`)

Error Code	HTTP Status	Description	Example Payload
`NOT_ALLOWED_FOR_ANONYMOUS_USER`	400	Cannot retrieve ID for anonymous users	`{"status": "error", "error": {"errorType": "USER_ERROR", "errorCode": "NOT_ALLOWED_FOR_ANONYMOUS_USER", "message": "Action not allowed for anonymous user."}}`
`USER_NOT_FOUND`	404	The specified user was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "USER_NOT_FOUND", "message": "Active user not found."}}`

Retrieve ID Update History (`GET /user/retrieve-id-update-history`)

Error Code	HTTP Status	Description	Example Payload
`NOT_ALLOWED_FOR_ANONYMOUS_USER`	400	Cannot retrieve ID history for anonymous users	`{"status": "error", "error": {"errorType": "USER_ERROR", "errorCode": "NOT_ALLOWED_FOR_ANONYMOUS_USER", "message": "Action not allowed for anonymous user."}}`
`USER_NOT_FOUND`	404	The specified user was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "USER_NOT_FOUND", "message": "Active user not found."}}`

Confirm ID Number (`POST /user/confirm-id-number`)

Error Code	HTTP Status	Description	Example Payload
`NOT_ALLOWED_FOR_ANONYMOUS_USER`	400	Cannot confirm ID for anonymous users	`{"status": "error", "error": {"errorType": "USER_ERROR", "errorCode": "NOT_ALLOWED_FOR_ANONYMOUS_USER", "message": "Action not allowed for anonymous user."}}`

Account Endpoints

Create Account (`POST /account/create`)

Error Code	HTTP Status	Description	Example Payload
`PRODUCT_NOT_ELIGIBLE`	400	The product is not eligible for this action (e.g., anonymous product)	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "PRODUCT_NOT_ELIGIBLE", "message": "Product not eligible for this action: createAccount.", "errorData": {"action": "createAccount"}}}`
`INVALID_SHIPPING_OPTION`	400	The specified shipping option is not available for this product	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "INVALID_SHIPPING_OPTION", "message": "Invalid card shipping option: express.", "errorData": {"shippingOption": "express"}}}`
`NOT_ALLOWED_FOR_CIP_STATUS`	400	User's CIP status does not allow account creation	`{"status": "error", "error": {"errorType": "USER_ERROR", "errorCode": "NOT_ALLOWED_FOR_CIP_STATUS", "message": "Action not allowed for user with CIP status: pend.", "errorData": {"cipStatus": "pend"}}}`
`WATCHLIST_CONFIRMED_OR_PENDING_REVIEW`	400	User is on watchlist and cannot create account	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "WATCHLIST_CONFIRMED_OR_PENDING_REVIEW", "message": "Action is blocked due to watchlist status: confirmed", "errorData": {"watchlistStatus": "confirmed"}}}`
`PRODUCT_COLLATERAL_CONFIG_ID_NOT_FOUND`	400	The specified collateral config ID was not found on the product	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "PRODUCT_COLLATERAL_CONFIG_ID_NOT_FOUND", "message": "Collateral config id: config123 not found on product id: prod456", "errorData": {"collateralConfigId": "config123", "productId": "prod456"}}}`
`ACCOUNT_CREATE_FAILED`	500	Account creation failed at the vendor level	`{"status": "error", "error": {"errorType": "ACCOUNT_ERROR", "errorCode": "ACCOUNT_CREATE_FAILED", "message": "Error creating account record."}}`
`USER_NOT_FOUND`	404	The specified user was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "USER_NOT_FOUND", "message": "Active user not found."}}`
`PRODUCT_NOT_FOUND`	404	The specified product was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "PRODUCT_NOT_FOUND", "message": "Active product not found."}}`

Edit Account (`PATCH /account/edit`)

Error Code	HTTP Status	Description	Example Payload
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACCOUNT_STATUS_NOT_ELIGIBLE`	400	Account status does not allow this action	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Account status for accountId: acc123 not eligible for this action: edit."}}`
`ACCOUNT_LOOKUP_ERROR`	500	Error occurred while looking up the account	`{"status": "error", "error": {"errorType": "LOOKUP_ERROR", "errorCode": "ACCOUNT_LOOKUP_ERROR", "message": "Account lookup failed."}}`

Edit Account Features (`PATCH /account/edit-account-features`)

Error Code	HTTP Status	Description	Example Payload
`INVALID_SHIPPING_OPTION`	400	The specified shipping option is not available for this product	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "INVALID_SHIPPING_OPTION", "message": "Invalid card shipping option: express.", "errorData": {"shippingOption": "express"}}}`
`FEATURE_TYPE_NOT_ELIGIBLE`	400	The feature type is not eligible for this product	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "FEATURE_TYPE_NOT_ELIGIBLE", "message": "Feature type not eligible: ach_transfers.", "errorData": {"featureType": "ach_transfers"}}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`PRODUCT_NOT_FOUND`	404	The specified product was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "PRODUCT_NOT_FOUND", "message": "Active product not found."}}`

ACH Account Endpoints

Create ACH Account (`POST /ach-account/create`)

Error Code	HTTP Status	Description	Example Payload
`LINKED_INSTITUTION_ACCOUNT_MISSING_ROUTING_OR_ACCOUNT_NUMBER`	400	The linked institution account is missing required routing or account number	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "LINKED_INSTITUTION_ACCOUNT_MISSING_ROUTING_OR_ACCOUNT_NUMBER", "message": "Linked institution account missing routing or account number: lia123.", "errorData": {"linkedInstitutionAccountId": "lia123"}}}`
`ACH_ACCOUNT_ALREADY_EXISTS`	400	An ACH account with these details already exists	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACH_ACCOUNT_ALREADY_EXISTS", "message": "ACH account already exists, achAccountId: ach456", "errorData": {"achAccountId": "ach456"}}}`
`ACH_ACCOUNT_CREATE_FAILED`	500	Failed to create ACH account	`{"status": "error", "error": {"errorType": "ACCOUNT_ERROR", "errorCode": "ACH_ACCOUNT_CREATE_FAILED", "message": "Error creating ach account record."}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`USER_NOT_FOUND`	404	The specified user was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "USER_NOT_FOUND", "message": "Active user not found."}}`
`LINKED_INSTITUTION_ACCOUNT_NOT_FOUND`	404	The linked institution account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "LINKED_INSTITUTION_ACCOUNT_NOT_FOUND", "message": "Linked institution account not found for: lia123.", "errorData": {"linkedInstitutionAccountId": "lia123"}}}`
`LINKED_INSTITUTION_ACCOUNT_TYPE_NOT_SUPPORTED`	400	The linked institution account type is not supported	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "LINKED_INSTITUTION_ACCOUNT_TYPE_NOT_SUPPORTED", "message": "Linked institution account type not supported: checking.", "errorData": {"linkedInstitutionAccountType": "checking"}}}`

Remove ACH Account (`DELETE /ach-account/remove`)

Error Code	HTTP Status	Description	Example Payload
`ACH_ACCOUNT_NOT_FOUND`	404	The specified ACH account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACH_ACCOUNT_NOT_FOUND", "message": "Active ach account not found."}}`
`ACCOUNT_NOT_FOUND`	404	The parent account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACH_ACCOUNT_LOOKUP_ERROR`	500	Error occurred while looking up ACH account	`{"status": "error", "error": {"errorType": "LOOKUP_ERROR", "errorCode": "ACH_ACCOUNT_LOOKUP_ERROR", "message": "ACH account lookup failed."}}`

Card Endpoints

Activate Card (`POST /card/activate`)

Error Code	HTTP Status	Description	Example Payload
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`
`CARD_STATUS_NOT_ELIGIBLE`	400	Card status does not allow activation	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: activation."}}`
`ACCOUNT_NOT_FOUND`	404	The parent account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`

Modify Card Status (`PATCH /card/modify-status`)

Error Code	HTTP Status	Description	Example Payload
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`
`CARD_STATUS_NOT_ELIGIBLE`	400	Card status does not allow this modification	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: freeze."}}`

Replace Card (`POST /card/replace`)

Error Code	HTTP Status	Description	Example Payload
`CARD_STATUS_NOT_ELIGIBLE`	400	Card status does not allow replacement (e.g., already closed)	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: replace.", "errorData": {"modifyReason": "replace"}}}`
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`

Reissue Card (`POST /card/reissue`)

Error Code	HTTP Status	Description	Example Payload
`CARD_STATUS_NOT_ELIGIBLE`	400	Card cannot be reissued (closed or already has pending reissue)	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: reissue.", "errorData": {"modifyReason": "Card has already been reissued"}}}`
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`

Reset PIN Fail Count (`POST /card/reset-pin-fail-count`)

Error Code	HTTP Status	Description	Example Payload
`CARD_STATUS_NOT_ELIGIBLE`	400	Card must be active or frozen to reset PIN fail count	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: ResetPINFailCard.", "errorData": {"modifyReason": "ResetPINFailCard"}}}`
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`

Mobile Wallet Provisioning (`POST /card/mobile-wallet-provisioning`)

Error Code	HTTP Status	Description	Example Payload
`CARD_STATUS_NOT_ELIGIBLE`	400	Card status does not allow mobile wallet provisioning	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: mobileWalletProvision.", "errorData": {"modifyReason": "mobileWalletProvision"}}}`
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`

Get Card Display URL (`POST /card/get-card-display-url`)

Error Code	HTTP Status	Description	Example Payload
`CARD_STATUS_NOT_ELIGIBLE`	400	Card status does not allow fetching display URL (e.g., closed)	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: getDisplayUrl."}}`
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`
`PRODUCT_INVALID_CONFIG_ID`	400	The display config ID is not valid for this product	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "PRODUCT_INVALID_CONFIG_ID", "message": "Invalid product config id: config123.", "errorData": {"productConfigId": "config123"}}}`

Get Card PIN Change Token (`POST /card/get-card-pin-change-token`)

Error Code	HTTP Status	Description	Example Payload
`CARD_STATUS_NOT_ELIGIBLE`	400	Card status does not allow PIN change (e.g., closed)	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: getCardPinUrl.", "errorData": {"modifyReason": "getCardPinUrl"}}}`
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`

Commit Card PIN Change (`POST /card/commit-card-pin-change`)

Error Code	HTTP Status	Description	Example Payload
`CARD_STATUS_NOT_ELIGIBLE`	400	Card status does not allow PIN change	`{"status": "error", "error": {"errorType": "INPUT_ERROR", "errorCode": "CARD_STATUS_NOT_ELIGIBLE", "message": "Card status not eligible for this modify action: commitCardPinChange.", "errorData": {"modifyReason": "commitCardPinChange"}}}`
`CARD_NOT_FOUND`	404	The specified card was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "CARD_NOT_FOUND", "message": "Active card not found."}}`

Transaction Endpoints

Create ACH Transaction (`POST /transaction/create-ach-transaction`)

Error Code	HTTP Status	Description	Example Payload
`ACH_ACCOUNT_LINKED_INSTITUTION_ACCOUNT_INSUFFICIENT_BALANCE`	400	Insufficient balance in the linked institution account	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACH_ACCOUNT_LINKED_INSTITUTION_ACCOUNT_INSUFFICIENT_BALANCE", "message": "Ach account linked institution account has insufficient balance.", "errorData": {"linkedInstitutionAccountId": "lia123", "achAccountId": "ach456"}}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACH_ACCOUNT_NOT_FOUND`	404	The specified ACH account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACH_ACCOUNT_NOT_FOUND", "message": "Active ach account not found."}}`
`ACCOUNT_STATUS_NOT_ELIGIBLE`	400	Account status does not allow ACH transactions	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Account status for accountId: acc123 not eligible for this action: achTransaction."}}`
`ACH_ACCOUNT_STATUS_NOT_ELIGIBLE`	400	ACH account status does not allow transactions	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACH_ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Ach account status not eligible for this action: transaction."}}`
`ACH_ACCOUNT_NOT_OWNED_BY_ACCOUNT`	400	ACH account does not belong to the specified account	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACH_ACCOUNT_NOT_OWNED_BY_ACCOUNT", "message": "Ach account is not owned by the account."}}`
`ACH_ACCOUNT_NOT_LINKED_TO_LINKED_INSTITUTION_ACCOUNT`	400	ACH account not linked to institution account (required for balance check)	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACH_ACCOUNT_NOT_LINKED_TO_LINKED_INSTITUTION_ACCOUNT", "message": "Ach account is not connected to a linked institution account.", "errorData": {"achAccountId": "ach456"}}}`
`ACH_REQUEST_NOT_VALID`	400	ACH request validation failed	`{"status": "error", "error": {"errorType": "INVALID_REQUEST", "errorCode": "ACH_REQUEST_NOT_VALID", "message": "Ach request not valid. Errors: validation error.", "errorData": {"validationErrors": ["validation error"]}}}`

Cancel ACH Transaction (`POST /transaction/cancel-ach-transaction`)

Error Code	HTTP Status	Description	Example Payload
`ACH_REQUEST_NOT_FOUND`	404	The specified ACH request was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACH_REQUEST_NOT_FOUND", "message": "Ach request not found for achReqId.", "errorData": {"achRequestId": "achReqId"}}}`
`ACH_REQUEST_NOT_VALID`	400	ACH request cannot be canceled (invalid status)	`{"status": "error", "error": {"errorType": "INVALID_REQUEST", "errorCode": "ACH_REQUEST_NOT_VALID", "message": "Ach request not valid. Errors: cannot cancel.", "errorData": {"validationErrors": ["cannot cancel"]}}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACCOUNT_STATUS_NOT_ELIGIBLE`	400	Account status does not allow this action	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Account status for accountId: acc123 not eligible for this action: cancelAch."}}`

Create Fee (`POST /transaction/create-fee`)

Error Code	HTTP Status	Description	Example Payload
`PRODUCT_FEE_INVALID`	400	The fee type is not valid for this product	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "PRODUCT_FEE_INVALID", "message": "Fee type invalid: monthly_fee.", "errorData": {"feeType": "monthly_fee"}}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACCOUNT_STATUS_NOT_ELIGIBLE`	400	Account status does not allow fee creation	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Account status for accountId: acc123 not eligible for this action: createFee."}}`
`INSUFFICIENT_BALANCE`	400	Account has insufficient balance for the fee	`{"status": "error", "error": {"errorType": "ACCOUNT_ERROR", "errorCode": "ACCOUNT_INSUFFICIENT_BALANCE", "message": "Insufficient balance: 100 for accountId: acc123.", "errorData": {"balance": "100", "accountId": "acc123"}}}`

Reverse Fee (`POST /transaction/reverse-fee`)

Error Code	HTTP Status	Description	Example Payload
`FEE_NOT_FOUND`	404	The specified fee transaction was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "FEE_NOT_FOUND", "message": "Fee not found for feeTransactionId: fee123.", "errorData": {"feeTransactionId": "fee123"}}}`
`FEE_NOT_REVERSIBLE`	400	The fee cannot be reversed (invalid status)	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "FEE_NOT_REVERSIBLE", "message": "Fee not reversible, status is: failed.", "errorData": {"feeStatus": "failed"}}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACCOUNT_STATUS_NOT_ELIGIBLE`	400	Account status does not allow fee reversal	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Account status for accountId: acc123 not eligible for this action: reverseFee."}}`

Create Adjustment (`POST /transaction/create-adjustment`)

Error Code	HTTP Status	Description	Example Payload
`ADJUSTMENT_DIRECTION_NOT_ALLOWED`	400	The requested debit/credit direction is not allowed for this adjustment type	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ADJUSTMENT_DIRECTION_NOT_ALLOWED", "message": "Adjustment direction not allowed: debit. Allowed directions: credit", "errorData": {"adjustmentType": "courtesy_credit", "direction": "debit", "allowedDirections": ["credit"]}}}`
`PRODUCT_ADJUSTMENT_INVALID`	400	The adjustment type is not valid for this product	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "PRODUCT_ADJUSTMENT_INVALID", "message": "Adjustment type invalid: custom_adj.", "errorData": {"adjustmentType": "custom_adj"}}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACCOUNT_STATUS_NOT_ELIGIBLE`	400	Account status does not allow adjustments	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Account status for accountId: acc123 not eligible for this action: createAdjustment."}}`

Reverse Adjustment (`POST /transaction/reverse-adjustment`)

Error Code	HTTP Status	Description	Example Payload
`ADJUSTMENT_NOT_FOUND`	404	The specified adjustment transaction was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ADJUSTMENT_NOT_FOUND", "message": "Adjustment not found for adjustmentTransactionId: adj123.", "errorData": {"adjustmentTransactionId": "adj123"}}}`
`ADJUSTMENT_NOT_REVERSIBLE`	400	The adjustment cannot be reversed (invalid status)	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ADJUSTMENT_NOT_REVERSIBLE", "message": "Adjustment not reversible, status is: failed.", "errorData": {"adjustmentStatus": "failed"}}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`

Create Payment (`POST /transaction/create-payment`)

Error Code	HTTP Status	Description	Example Payload
`PRODUCT_PAYMENT_INVALID`	400	The payment type is not valid for this product	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "PRODUCT_PAYMENT_INVALID", "message": "Payment type invalid: online_payment.", "errorData": {"paymentType": "online_payment"}}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACCOUNT_STATUS_NOT_ELIGIBLE`	400	Account status does not allow payments	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Account status for accountId: acc123 not eligible for this action: createPayment."}}`

Create A2A Transfer (`POST /transaction/create-a2a-transfer`)

Error Code	HTTP Status	Description	Example Payload
`PRODUCT_A2A_INVALID`	400	A2A transfers are not enabled for this product	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "PRODUCT_A2A_NOT_ELIGIBLE", "message": "Product is not eligible for A2A transfers."}}`
`A2A_SENDER_RECEIVER_SAME_ACCOUNT`	400	Cannot transfer to the same account	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "A2A_SENDER_RECEIVER_SAME", "message": "Sender and receiver cannot be the same."}}`
`ACCOUNT_NOT_FOUND`	404	The specified account was not found (sender or receiver)	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "ACCOUNT_NOT_FOUND", "message": "Active account not found."}}`
`ACCOUNT_STATUS_NOT_ELIGIBLE`	400	Account status does not allow A2A transfers	`{"status": "error", "error": {"errorType": "INVALID_INPUT", "errorCode": "ACCOUNT_STATUS_NOT_ELIGIBLE", "message": "Account status for accountId: acc123 not eligible for this action: a2aTransfer."}}`

Common Errors

These errors can occur across multiple endpoints:

Resource Not Found Errors

Error Code	Description
`USER_NOT_FOUND`	The specified user was not found
`ACCOUNT_NOT_FOUND`	The specified account was not found
`CARD_NOT_FOUND`	The specified card was not found
`ACH_ACCOUNT_NOT_FOUND`	The specified ACH account was not found
`PRODUCT_NOT_FOUND`	The specified product was not found
`LINKED_INSTITUTION_NOT_FOUND`	The specified linked institution was not found
`LINKED_INSTITUTION_ACCOUNT_NOT_FOUND`	The specified linked institution account was not found

Lookup Errors

Error Code	Description
`USER_LOOKUP_ERROR`	Error occurred while looking up user data
`ACCOUNT_LOOKUP_ERROR`	Error occurred while looking up account data
`ACH_ACCOUNT_LOOKUP_ERROR`	Error occurred while looking up ACH account data
`PRODUCT_LOOKUP_ERROR`	Error occurred while looking up product data
`LINKED_INSTITUTION_LOOKUP_ERROR`	Error occurred while looking up linked institution data

ZTM (Zero Touch Monitoring) Errors

Error Code	Description
`WORKFLOW_TYPE_NOT_FOUND`	No workflow type found for this action
`WORKFLOW_NOT_FOUND`	Workflow configuration not found
`WORKFLOW_NOT_ACTIVE`	Workflow is not active
`ZTM_WORKFLOW_PROVIDER_ERROR`	Error from ZTM workflow provider
`ZTM_NO_GO`	Transaction was blocked by ZTM risk assessment

Validation Errors

Error Code	Description
`INVALID_USER_IDNUMBER`	The provided ID number format is invalid
`INVALID_SHIPPING_OPTION`	The specified shipping option is invalid
`PRODUCT_INVALID_CONFIG_ID`	The display config ID is invalid
`INVALID_TRANSACTION`	Transaction data is invalid

HTTP Status Codes

Status Code	Meaning	Usage
400	Bad Request	Invalid input, validation failures, duplicate resources, business rule violations
404	Not Found	Requested resource does not exist
500	Internal Server Error	System errors, lookup failures, vendor errors

Note: Most duplicate/conflict scenarios return 400 rather than 409.

Error Handling Best Practices

Always check errorCode: Use the error code (not message) for programmatic handling
Log errorData: Additional context in errorData helps with debugging
Display user-friendly messages: Don't show raw error messages to end users
Retry logic: For 500-level errors, implement exponential backoff
Validation: Validate input client-side before API calls to reduce errors

Support

For questions about specific error codes or error handling, please contact Spidr support or refer to the main API documentation.

Table of Contents

Error Response Structure

Error Types

User Endpoints

Create User (POST /user/create)

Edit User (PATCH /user/edit)

Edit ID Number (PATCH /user/edit-id-number)

Update User CIP Status (PATCH /user/update-cip-status)

Archive User (PATCH /user/archive)

Retrieve ID Number (GET /user/retrieve-id-number)

Retrieve ID Update History (GET /user/retrieve-id-update-history)

Confirm ID Number (POST /user/confirm-id-number)

Account Endpoints

Create Account (POST /account/create)

Edit Account (PATCH /account/edit)

Edit Account Features (PATCH /account/edit-account-features)

ACH Account Endpoints

Create ACH Account (POST /ach-account/create)

Remove ACH Account (DELETE /ach-account/remove)