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)
VALIDATION: Request schema validation failures (returned with error code INVALID_REQUEST)
NOT_FOUND: Resource not found errors
NOT_ELIGIBLE: The product, user, or feature is not eligible for the requested action
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)
ZTM_ERROR: Zero Touch Monitoring workflow errors
FORBIDDEN: Operation not allowed in this environment (403)
CONFLICT: Resource state conflict (409)
UNKNOWN_ERROR: Unexpected server error (500)

User Endpoints

Create User (`POST /v1/user/create`)

Error Code	HTTP Status	Description	Example Payload
`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 /v1/user/:id`)

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."}}`

Edit ID Number (`PATCH /v1/user/:id/editIdNumber`)

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 /v1/user/:id/cipStatus`)

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 /v1/user/:id/archiveUser`)

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."}}`

Archive Entity (`PATCH /v1/entity/:id/archiveEntity`)

Error Code	HTTP Status	Description	Example Payload
`USER_ARCHIVE_ACTIVE_ACCOUNTS_EXIST`	400	Cannot archive entity 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 entity was not found	`{"status": "error", "error": {"errorType": "NOT_FOUND", "errorCode": "USER_NOT_FOUND", "message": "Active user not found."}}`

Retrieve ID Number (`GET /v1/user/:id/retrieveIdNumber`)

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 /v1/user/:id/retrieveIdUpdateHistory`)

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 /v1/user/:id/confirmIdNumber`)

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 /v1/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 /v1/account/:id`)

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."}}`

Edit Account Features (`PATCH /v1/account/:id/editAccountFeatures`)

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 /v1/achaccount/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 /v1/achaccount/:id`)

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."}}`

Card Endpoints

Activate Card (`POST /v1/card/:cardId/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 /v1/card/:cardId/modifyStatus`)

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 /v1/card/:cardId/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 /v1/card/:cardId/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 /v1/card/:cardId/resetPinFailCount`)

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 /v1/card/:cardId/mobileWalletProvision`)

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 /v1/card/:cardId/displayUrl`)

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 /v1/card/:cardId/pinChangeToken`)

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 /v1/card/:cardId/commitPinChange`)

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 /v1/transaction/createAchTransfer`)

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 /v1/transaction/cancelAchTransfer`)

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 /v1/transaction/createFee`)

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."}}`
`ACCOUNT_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 /v1/transaction/reverseFee`)

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 /v1/transaction/createAdjustment`)

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 /v1/transaction/reverseAdjustment`)

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 /v1/transaction/createPayment`)

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 /v1/transaction/createA2ATransfer`)

Error Code	HTTP Status	Description	Example Payload
`PRODUCT_A2A_NOT_ELIGIBLE`	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`	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
`GROUP_NOT_FOUND`	The specified group 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

ZTM (Zero Touch Monitoring) Errors

Error Code	Description
`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

Feature Error Reference

Error codes for feature areas not covered by the endpoint tables above. All responses use the standard error structure shown at the top of this page.

Request & Platform Errors

These can occur on any endpoint.

Error Code	HTTP Status	Error Type	Description
`INVALID_REQUEST`	400	`INVALID_REQUEST`	Request body or parameters failed schema validation; the message field lists the specific failures
`DUPLICATE_REQUEST_ID`	400	`INVALID_REQUEST`	The requestId was already used by a previous request
`MISSING_REQUEST_ID`	400	`INVALID_REQUEST`	A unique requestId is required
`OPERATION_NOT_ALLOWED_IN_PRODUCTION`	403	`FORBIDDEN`	This operation (e.g. a simulation endpoint) is only available in non-production environments
`OPERATION_REQUIRES_SANDBOX_ENVIRONMENT`	403	`FORBIDDEN`	This operation is only available in the sandbox environment

User & Product Eligibility Errors

Returned by user/entity create and edit endpoints when product rules are not satisfied.

Error Code	HTTP Status	Error Type	Description
`MISSING_REQUIRED_USER_FIELDS`	400	`INVALID_INPUT`	Missing required user fields:
`MISSING_POSTAL_CODE`	400	`INVALID_INPUT`	postalCode is required for the provided countryCode
`INVALID_PHONE_NUMBER`	400	`INVALID_INPUT`	Only phone numbers from the following countries are allowed:
`INVALID_LINKED_USER`	400	`INVALID_INPUT`	Invalid linked user:
`UNSUPPORTED_ACH_ACCOUNT_TYPE`	400	`INVALID_INPUT`	The provided ach account type is not supported
`PRODUCT_NOT_ELIGIBLE_FOR_USER_TYPE`	400	`INVALID_INPUT`	Product not eligible for user type:
`MINIMUM_AGE_RULE_NOT_SATISFIED`	400	`INVALID_INPUT`	The user does not meet the product's minimum age requirement
`MAXIMUM_AGE_RULE_NOT_SATISFIED`	400	`INVALID_INPUT`	The user exceeds the product's maximum age limit
`USER_ID_TYPE_RULE_NOT_SATISFIED`	400	`INVALID_INPUT`	The user's idType is not allowed by the product's ID-type rule
`COUNTRY_CODE_RULE_NOT_SATISFIED`	400	`INVALID_INPUT`	The user's country code is not allowed by the product's country rule

Entity & Beneficial Owner Errors

Returned by entity create/edit and beneficial-owner endpoints.

Error Code	HTTP Status	Error Type	Description
`ENTITY_NOT_FOUND`	404	`NOT_FOUND`	Active entity not found
`BENEFICIAL_OWNER_NOT_FOUND_OR_INVALID`	400	`INVALID_INPUT`	Beneficial owner(s) not found or invalid:
`BENEFICIAL_OWNER_PERCENTAGE_INVALID`	400	`INVALID_INPUT`	Beneficial owner percentage can not be greater than 100%
`BENEFICIAL_OWNERS_CIP_STATUS_NOT_PASS`	400	`INVALID_INPUT`	All beneficial owners must first pass KYC

Account Errors (Secondary Accounts, BYOP, Statements)

Returned by account create/edit, statement, and ACH endpoints.

Error Code	HTTP Status	Error Type	Description
`ACCOUNT_CREATION_BLOCKED_DUE_TO_ERROR`	400	`ACCOUNT_ERROR`	Account creation blocked due to error with previous attempt. Account ID:
`ACCOUNT_INSUFFICIENT_BALANCE`	400	`ACCOUNT_ERROR`	Insufficient balance:
`ACCOUNT_VARIANT_NOT_ELIGIBLE`	400	`INVALID_INPUT`	Account variant
`ACCOUNT_STATUS_REASON_NOT_FOUND`	404	`NOT_FOUND`	Account status reason not found:
`ACCOUNT_NUMBER_REQUIRED_FOR_BYOP`	400	`INVALID_INPUT`	Account number is required for byop
`ACCOUNT_NUMBER_NOT_ALLOWED_FOR_VENDOR`	400	`INVALID_INPUT`	Account number is not allowed for vendor:
`BYOP_ACCOUNT_NUMBER_ALREADY_EXISTS`	400	`INVALID_INPUT`	BYOP account number already exists:
`PRIMARY_ACCOUNT_STATUS_NOT_ELIGIBLE`	400	`INVALID_INPUT`	Secondary account creation is not allowed because the primary account is in an ineligible status:
`PRIMARY_ACCOUNT_HAS_OPEN_SECONDARY_ACCOUNTS`	400	`INVALID_INPUT`	Cannot close primary account. The following secondary accounts must be closed first:
`ACCOUNT_NOT_ELIGIBLE_FOR_SECONDARY_ACCOUNT_LINKING`	400	`INVALID_INPUT`	Account is not eligible for secondary account linking
`PRODUCT_NOT_ELIGIBLE_FOR_SECONDARY_ACCOUNT_LINKING`	400	`INVALID_INPUT`	Product
`FEATURE_TYPE_NOT_FOUND`	404	`NOT_FOUND`	Feature type not found:
`ACCOUNT_STATEMENT_DATA_NOT_RETRIEVABLE`	400	`NOT_FOUND`	Account statement data not retrievable for accountId:
`PRODUCT_STATEMENT_CONFIG_ID_NOT_FOUND`	400	`NOT_FOUND`	Statement config id:
`ACH_ACCOUNT_NAME_ALREADY_IN_USE`	400	`INVALID_INPUT`	An ACH account named '' already exists for this customer
`ACH_TRANSACTION_NOT_FOUND`	404	`NOT_FOUND`	Ach transaction not found for
`ACH_TRANSACTION_NOT_ELIGIBLE_FOR_CANCELLATION`	400	`INVALID_INPUT`	Ach transaction not eligible for cancellation

A2A Transfer Errors (additional)

Returned by POST /v1/transaction/createA2ATransfer in addition to the codes listed above.

Error Code	HTTP Status	Error Type	Description
`A2A_REQUIRES_SAME_USER`	400	`INVALID_INPUT`	This A2A type requires sender and receiver to belong to the same user
`A2A_SENDER_RECEIVER_VENDOR_MISMATCH`	400	`INVALID_INPUT`	Sender and receiver vendor mismatch. Sender vendor:
`PRODUCT_A2A_TYPE_INVALID`	400	`INVALID_INPUT`	A2A type invalid:
`PRODUCT_A2A_TYPE_INVALID_RECEIVER`	400	`INVALID_INPUT`	A2A type invalid on receiver product:

Round-Up Errors

Returned by the /v1/roundup enrollment and sweep endpoints.

Error Code	HTTP Status	Error Type	Description
`ROUNDUP_NOT_ENABLED`	400	`INVALID_REQUEST`	Round-Up is not enabled for this product
`ROUNDUP_ENROLLMENT_NOT_FOUND`	404	`INVALID_REQUEST`	Round-Up enrollment not found
`ROUNDUP_ENROLLMENT_CLOSED`	400	`INVALID_REQUEST`	Closed round-up enrollments are terminal and cannot be modified
`ROUNDUP_INVALID_STATUS_TRANSITION`	400	`INVALID_INPUT`	Invalid round-up enrollment status transition
`ROUNDUP_FIXED_AMOUNT_REQUIRED`	400	`INVALID_INPUT`	fixedAmount is required for fixed amount round-up mode
`ROUNDUP_PERCENTAGE_TOTAL_INVALID`	400	`INVALID_INPUT`	percentages must total 100
`ROUNDUP_INVALID_CADENCE_MAX`	400	`INVALID_INPUT`	cadenceMaxAmount must be greater than or equal to zero
`ROUNDUP_INVALID_MINIMUM_SWEEP_AMOUNT`	400	`INVALID_INPUT`	minimumSweepAmount must be greater than or equal to zero
`ROUNDUP_ACH_FUNDING_ACCOUNT_LIMIT`	400	`INVALID_INPUT`	ACH round-up funding enrollments may only have one funding account
`ROUNDUP_ACH_FUNDING_ACCOUNT_INVALID`	400	`INVALID_INPUT`	Round-up ACH funding account must be active and belong to the enrollment user
`ROUNDUP_ACH_FUNDING_ACCOUNT_RECEIVING_ACCOUNT_MISMATCH`	400	`INVALID_INPUT`	Round-up ACH funding account must belong to the receiving account
`ROUNDUP_ACH_HOLD_DAYS_INVALID`	400	`INVALID_INPUT`	Round-up ACH hold days must be greater than or equal to
`ROUNDUP_ACH_HOLD_DAYS_NOT_ELIGIBLE`	400	`INVALID_INPUT`	Round-up ACH hold-day modification is not enabled for this product's ACH configuration
`ROUNDUP_TRACKING_ACCOUNT_USER_MISMATCH`	400	`INVALID_INPUT`	Round-up tracking accounts must belong to the enrollment user
`ROUNDUP_FUNDING_ACCOUNT_USER_MISMATCH`	400	`INVALID_INPUT`	Round-up funding accounts must belong to the enrollment user
`ROUNDUP_RECEIVING_ACCOUNT_USER_MISMATCH`	400	`INVALID_INPUT`	Round-up receiving account does not belong to the enrollment user

Bill Pay Errors

Returned by the /v1/billpay endpoints.

Error Code	HTTP Status	Error Type	Description
`BILL_PAY_NOT_ENABLED`	400	`INVALID_REQUEST`	Bill pay is not enabled for this product
`BILLER_NOT_FOUND`	400	`INVALID_REQUEST`	Biller not found:
`BILLER_ALREADY_CLOSED`	400	`INVALID_REQUEST`	Biller is already closed:
`BILLPAY_REQUEST_NOT_FOUND`	400	`INVALID_REQUEST`	Bill pay request not found:

Secured Credit Errors

Returned by secured-credit account creation and credit summary endpoints.

Error Code	HTTP Status	Error Type	Description
`SECURED_CREDIT_AUTHORIZED_USER_LIMIT_REACHED`	400	`INVALID_INPUT`	The primary cardholder's account has reached its authorized-user limit
`SECURED_CREDIT_ROLE_NOT_SUPPORTED`	400	`INVALID_INPUT`	This secured-credit account role does not support credit-summary refresh
`CREDIT_SUMMARY_NOT_AVAILABLE`	409	`CONFLICT`	A credit summary is not currently available for this account

Group Errors

Returned by the /v1/group endpoints.

Error Code	HTTP Status	Error Type	Description
`GROUP_HAS_CHILDREN`	400	`INVALID_INPUT`	Group has children
`GROUP_HAS_ACCOUNTS`	400	`INVALID_INPUT`	Group has accounts
`INVALID_GROUP_LEVEL`	400	`INVALID_INPUT`	Maximum group hierarchy depth exceeded
`GROUP_CLOSED`	400	`INVALID_INPUT`	Group is closed
`ACCOUNT_NOT_ELIGIBLE_FOR_GROUP_LINKING`	400	`INVALID_INPUT`	Account(s) is not eligible for group linking:

Linked Institution Errors (additional)

Returned by the linked-institution endpoints in addition to the codes listed above.

Error Code	HTTP Status	Error Type	Description
`LINKED_INSTITUTION_SESSION_NOT_FOUND`	404	`NOT_FOUND`	Linked institution session not found for:
`LINKED_INSTITUTION_ACCOUNTS_NOT_FOUND_FOR_LINKED_INSTITUTION`	404	`NOT_FOUND`	Linked institution accounts not found for linked institution:
`LINKED_INSTITUTION_ACCOUNT_BALANCE_NOT_FOUND`	404	`NOT_FOUND`	Linked institution account balance not found for:
`LINKED_INSTITUTION_UNLINKED`	400	`INVALID_INPUT`	Linked institution unlinked for:
`LINKED_INSTITUTION_ACCOUNT_UNLINKED`	400	`INVALID_INPUT`	Linked institution account has been unlinked (deselected) for:
`INVALID_LINKED_INSTITUTION_SEARCH_PARAMETERS`	400	`INVALID_INPUT`	Linked institution ID or linked institution account ID or userId is required

ZTM API Errors (Sessions, IDV, Watchlist, Actions)

Returned by the ZTM API session, IDV, KYB, watchlist-screening, and action endpoints.

Error Code	HTTP Status	Error Type	Description
`INVALID_SESSION_KEY`	400	`INVALID_INPUT`	Invalid session key
`ZTM_SESSION_NOT_FOUND`	404	`NOT_FOUND`	Session could not be found
`ZTM_PRODUCT_NOT_ENROLLED`	400	`NOT_ELIGIBLE`	Product not enrolled for companyId:
`ZTM_REQUIRES_PASSING_IDV_SESSION`	400	`NOT_ELIGIBLE`	Passing IDV Session not found for user: . You must bypass ZTM for this call
`IDV_SESSION_NOT_FOUND`	404	`NOT_FOUND`	The specified IDV session was not found
`IDV_SESSION_ALREADY_COMPLETED`	400	`INVALID_INPUT`	IDV session is already completed and cannot be modified
`IDV_SESSION_NOT_PENDING_REVIEW`	400	`INVALID_INPUT`	IDV session is not pending review. Current status:
`IDV_SESSION_DOES_NOT_REQUIRE_MANUAL_REVIEW`	400	`INVALID_INPUT`	The IDV session does not require manual review
`IDV_SESSION_DOCUMENT_ALREADY_EXISTS`	400	`INVALID_INPUT`	An IDV session document already exists for this session
`IDV_PENDING_REVIEW`	400	`INVALID_INPUT`	IDV session requires review before this action can be completed
`IDV_TEMPLATE_NOT_ALLOWED_FOR_PRODUCT`	400	`INVALID_INPUT`	IDV template:
`KYB_SESSION_NOT_FOUND`	404	`NOT_FOUND`	KYB session not found for userId:
`KYB_DOCUMENT_CONTENT_NOT_FOUND`	404	`NOT_FOUND`	KYB document content not found for documentId:
`WATCHLIST_PENDING_HIT`	400	`INVALID_INPUT`	Unable to proceed. Decision required on pending watchlist hit first
`WATCHLIST_HITS_NOT_FOUND`	404	`NOT_FOUND`	Watchlist hit IDs not found in screening:
`PENDING_WATCHLIST_SCREENINGS_FOUND`	400	`INVALID_INPUT`	Unable to proceed. Pending watchlist screenings found for IDV session:
`USER_ALREADY_ENROLLED_IN_WATCHLIST_SCREENING`	400	`NOT_ELIGIBLE`	User already enrolled in watchlist screening
`DUPLICATE_HIT_IDS_IN_CONFIRMED_AND_DISMISSED`	400	`INVALID_REQUEST`	Hit IDs cannot appear in both confirmed and dismissed arrays:
`SPIDR_ACTION_NOT_FOUND`	404	`NOT_FOUND`	Spidr Action not found
`SPIDR_ACTION_NOT_ELIGIBLE`	400	`INVALID_REQUEST`	Spidr action type: not eligible
`SPIDR_ACTION_TYPE_MISMATCH`	400	`INVALID_REQUEST`	Input action type:
`SPIDR_ACTION_STATUS_NOT_ELIGIBLE_FOR_UPDATE`	400	`INVALID_REQUEST`	SpidrAction
`SPIDR_ACTION_DECISION_ALREADY_MADE`	400	`INVALID_REQUEST`	Spidr action:
`SPIDR_ACTION_ALREADY_COMPLETED`	400	`INVALID_REQUEST`	Spidr action: is already completed and cannot be modified
`SPIDR_ACTION_PENDING_RISK_LEVEL`	400	`INVALID_REQUEST`	Spidr action: has a pending risk level

HTTP Status Codes

Status Code	Meaning	Usage
400	Bad Request	Invalid input, validation failures, duplicate resources, business rule violations
403	Forbidden	Operation not allowed in this environment (e.g. simulation endpoints in production)
404	Not Found	Requested resource does not exist
409	Conflict	Resource state conflict (e.g. credit summary not yet available)
500	Internal Server Error	Unexpected system or vendor errors; retry with exponential backoff

Note: Most duplicate/conflict scenarios return 400 rather than 409; a small number of state conflicts return 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 /v1/user/create)

Edit User (PATCH /v1/user/:id)

Edit ID Number (PATCH /v1/user/:id/editIdNumber)

Update User CIP Status (PATCH /v1/user/:id/cipStatus)

Archive User (PATCH /v1/user/:id/archiveUser)

Archive Entity (PATCH /v1/entity/:id/archiveEntity)

Retrieve ID Number (GET /v1/user/:id/retrieveIdNumber)

Retrieve ID Update History (GET /v1/user/:id/retrieveIdUpdateHistory)

Confirm ID Number (POST /v1/user/:id/confirmIdNumber)