Skip to main content

Error Codes Reference

Reference of Weavr MultiMulti Weavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise. API error codes with descriptions and solutions.

Error code categories​

Error codes are grouped by functional area for easier navigation:

Authentication & Authorization​

AUTH_001 - UNAUTHORIZED​

  • HTTP Status: 401
  • Description: Missing or invalid API key/token
  • Solution: Include valid api-key header

AUTH_002 - FORBIDDEN​

  • HTTP Status: 403
  • Description: Insufficient permissions for operation
  • Solution: Verify user permissions and account state

AUTH_003 - TOKEN_EXPIRED​

  • HTTP Status: 401
  • Description: Authentication token has expired
  • Solution: Login again to get fresh token
  • Note: Stepped-up tokens expire after 5 minutes of inactivity

AUTH_004 - INVALID_CREDENTIALS​

  • HTTP Status: 401
  • Description: Email/password combination incorrect
  • Solution: Verify credentials, check for typos

AUTH_005 - ACCOUNT_LOCKED​

  • HTTP Status: 403
  • Description: Too many failed login attempts
  • Solution: Wait for lockout period or contact support

AUTH_006 - STEP_UP_REQUIRED​

  • HTTP Status: 403
  • Description: Operation requires SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics)./step-up authentication
  • Solution: Complete step-up flow before retrying

AUTH_007 - CHANNEL_NOT_REGISTERED​

  • HTTP Status: 400
  • Description: Authentication factor (SMS) not enrolled
  • Solution: Enrol SMS via /authentication_factors/otp/SMS

AUTH_008 - INVALID_VERIFICATION_CODE​

  • HTTP Status: 400
  • Description: OTP/verification code incorrect or expired
  • Solution: Request new code, ensure using latest

AUTH_009 - PASSWORD_POLICY_VIOLATION​

  • HTTP Status: 400
  • Description: Password doesn't meet security requirements
  • Solution: Min 8 chars, uppercase, lowercase, number, special character

AUTH_010 - SESSION_EXPIRED​

  • HTTP Status: 401
  • Description: User session has timed out
  • Solution: Re-authenticate user

Identity & KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers./KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers.​

IDENTITY_001 - OWNER_IDENTITY_NOT_VERIFIED​

  • HTTP Status: 403
  • Description: Corporate/consumer needs KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers./KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. verification (and email/mobile verification in production)
  • Solution: Complete KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. process or use Simulator API (sandbox)

IDENTITY_002 - EMAIL_NOT_VERIFIED​

  • HTTP Status: 403
  • Description: Email address requires verification
  • Solution: Complete email verification flow

IDENTITY_003 - MOBILE_NOT_VERIFIED​

  • HTTP Status: 403
  • Description: Mobile number not verified
  • Solution: Complete SMS enrolment process

IDENTITY_004 - DUPLICATE_EMAIL​

  • HTTP Status: 409
  • Description: Email already registered
  • Solution: Use different email or login with the existing user

IDENTITY_005 - DUPLICATE_IDENTITY​

  • HTTP Status: 409
  • Description: Identity already exists with these details
  • Solution: Check for existing registration

IDENTITY_006 - KYB_REJECTED​

  • HTTP Status: 403
  • Description: KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. verification failed
  • Solution: Review rejection reason, resubmit documentation

IDENTITY_007 - INVALID_COMPANY_TYPE​

  • HTTP Status: 400
  • Description: Company type not supported
  • Solution: Use valid enum: LIMITED_LIABILITY_COMPANY, etc.

IDENTITY_008 - INVALID_COUNTRY​

  • HTTP Status: 400
  • Description: Country not supported for operations
  • Solution: Check supported countries list

IDENTITY_009 - ABANDONED_USER​

  • HTTP Status: 403
  • Description: User abandoned onboarding (email expired)
  • Solution: Re-register the user as new

IDENTITY_010 - USER_SUSPENDED​

  • HTTP Status: 403
  • Description: User account suspended by admin
  • Solution: Contact support for resolution

Managed accountsManaged Account An account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr.​

ACCOUNT_001 - INSUFFICIENT_BALANCE​

  • HTTP Status: 400
  • Description: Account balance too low for operation
  • Solution: Add funds before retrying

ACCOUNT_002 - DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN​

  • HTTP Status: 400
  • Description: Account needs IBANIBAN International Bank Account Number - a standardized international bank account identifier. Managed accounts can be assigned an IBAN to enable wire transfers to and from bank accounts outside of Weavr. IBANs are required for EUR accounts and enable SEPA transfers. for receiving funds
  • Solution: Upgrade via /managed_accounts/{id}/iban

ACCOUNT_003 - ACCOUNT_BLOCKED​

  • HTTP Status: 403
  • Description: Account blocked for security/compliance reasons
  • Solution: Contact support for unblock

ACCOUNT_004 - CURRENCY_MISMATCH​

  • HTTP Status: 400
  • Description: Operation currency doesn't match the account
  • Solution: Use correct currency or create an account in the same currency

ACCOUNT_005 - DUPLICATE_ACCOUNT​

  • HTTP Status: 409
  • Description: Account with same details already exists
  • Solution: Use existing account or change parameters

ACCOUNT_006 - INVALID_PROFILE_ID​

  • HTTP Status: 400
  • Description: Managed accountManaged Account An account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr./card profile ID invalid/inactive
  • Solution: Use valid profile ID from Portal

ACCOUNT_007 - ACCOUNT_CLOSED​

  • HTTP Status: 403
  • Description: Account has been closed
  • Solution: Create new account

ACCOUNT_008 - IBAN_ALREADY_ASSIGNED​

  • HTTP Status: 409
  • Description: Account already has IBANIBAN International Bank Account Number - a standardized international bank account identifier. Managed accounts can be assigned an IBAN to enable wire transfers to and from bank accounts outside of Weavr. IBANs are required for EUR accounts and enable SEPA transfers.
  • Solution: Use existing IBANIBAN International Bank Account Number - a standardized international bank account identifier. Managed accounts can be assigned an IBAN to enable wire transfers to and from bank accounts outside of Weavr. IBANs are required for EUR accounts and enable SEPA transfers. details

ACCOUNT_009 - STATEMENT_NOT_READY​

  • HTTP Status: 404
  • Description: Statement not yet generated
  • Solution: Wait for statement generation (usually monthly)

ACCOUNT_010 - EXCEEDS_ACCOUNT_LIMIT​

  • HTTP Status: 400
  • Description: Exceeds maximum accounts per identity
  • Solution: Close unused accounts or contact support

Managed cardsManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User.​

CARD_001 - CARD_BLOCKED​

  • HTTP Status: 403
  • Description: Card blocked due to a security/user request
  • Solution: Unblock via API or issue replacement

CARD_002 - CARD_EXPIRED​

  • HTTP Status: 400
  • Description: Card past expiry date
  • Solution: Issue replacement card

CARD_003 - INSUFFICIENT_CARD_BALANCE​

  • HTTP Status: 400
  • Description: Card balance too low (prepaid modePrepaid Mode A card mode where the card has its own balance and purchases are authorised based on this balance. Cards in prepaid mode can be topped up with funds and support transactions such as transfers and sends. If there are insufficient funds, purchases are declined until the card has sufficient funds.)
  • Solution: TransferTransfer A transaction that moves funds between instruments managed by Weavr. The source and destination instruments of a transfer transaction must be owned by the same identity. Transfers can be scheduled for future execution and can be performed in bulk operations. funds to card

CARD_004 - EXCEEDS_SPENDING_LIMIT​

  • HTTP Status: 400
  • Description: Transaction exceeds card spending limits
  • Solution: Adjust limits or split transaction

CARD_005 - INVALID_PIN​

  • HTTP Status: 401
  • Description: Incorrect PIN entered
  • Solution: Use correct PIN or reset

CARD_006 - CARD_NOT_ACTIVATED​

  • HTTP Status: 403
  • Description: Physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. not yet activated
  • Solution: Activate card first

CARD_007 - DUPLICATE_CARD​

  • HTTP Status: 409
  • Description: Card with same details exists
  • Solution: Use existing card

CARD_008 - INVALID_CARD_MODE​

  • HTTP Status: 400
  • Description: Invalid mode (DEBIT_MODE/PREPAID_MODE)
  • Solution: Use valid card mode enum

CARD_009 - BILLING_ADDRESS_REQUIRED​

  • HTTP Status: 400
  • Description: Billing address missing for card
  • Solution: Provide complete billing address

CARD_010 - NAME_ON_CARD_INVALID​

  • HTTP Status: 400
  • Description: Name contains invalid characters
  • Solution: Use only letters, spaces, hyphens

Transactions​

TRANS_001 - INVALID_INSTRUMENT_TYPE​

  • HTTP Status: 400
  • Description: Wrong instrument type in request
  • Solution: Use plural: managed_accounts, managed_cards

TRANS_002 - SOURCE_INSTRUMENT_NOT_FOUND​

  • HTTP Status: 404
  • Description: Source account/card doesn't exist
  • Solution: Verify source instrument ID

TRANS_003 - DESTINATION_INSTRUMENT_NOT_FOUND​

  • HTTP Status: 404
  • Description: Destination account/card doesn't exist
  • Solution: Verify destination instrument ID

TRANS_004 - INVALID_AMOUNT​

  • HTTP Status: 400
  • Description: Amount invalid (negative, zero, format)
  • Solution: Use positive integer in minor units

TRANS_005 - EXCEEDS_TRANSACTION_LIMIT​

  • HTTP Status: 400
  • Description: Transaction exceeds configured limits
  • Solution: Split transaction or request limit increase

TRANS_006 - DUPLICATE_TRANSACTION​

  • HTTP Status: 409
  • Description: Duplicate transaction detected
  • Solution: Use unique idempotency key

TRANS_007 - TRANSFER_NOT_ALLOWED​

  • HTTP Status: 403
  • Description: TransferTransfer A transaction that moves funds between instruments managed by Weavr. The source and destination instruments of a transfer transaction must be owned by the same identity. Transfers can be scheduled for future execution and can be performed in bulk operations. between these instruments not allowed
  • Solution: Check transferTransfer A transaction that moves funds between instruments managed by Weavr. The source and destination instruments of a transfer transaction must be owned by the same identity. Transfers can be scheduled for future execution and can be performed in bulk operations. rules and restrictions

TRANS_008 - INVALID_BENEFICIARY​

  • HTTP Status: 400
  • Description: BeneficiaryBeneficiary A trusted recipient for payments that includes both information about the business or individual as well as their bank account or instrument details. When using trusted beneficiaries, customers may be allowed to skip Strong Customer Authentication (SCA) when executing Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. details invalid/incomplete
  • Solution: Provide complete beneficiaryBeneficiary A trusted recipient for payments that includes both information about the business or individual as well as their bank account or instrument details. When using trusted beneficiaries, customers may be allowed to skip Strong Customer Authentication (SCA) when executing Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. information

TRANS_009 - TRANSACTION_DECLINED​

  • HTTP Status: 400
  • Description: Transaction declined by processor
  • Solution: Check decline reason, retry if temporary

TRANS_010 - REVERSAL_NOT_ALLOWED​

  • HTTP Status: 403
  • Description: Transaction cannot be reversed
  • Solution: Only certain transaction types reversible

Validation & Data​

VALID_001 - MISSING_REQUIRED_FIELD​

  • HTTP Status: 400
  • Description: Required field not provided
  • Solution: Include all required fields as per API spec

VALID_002 - INVALID_FIELD_FORMAT​

  • HTTP Status: 400
  • Description: Field format incorrect (email, phone, etc.)
  • Solution: Follow format requirements

VALID_003 - FIELD_TOO_LONG​

  • HTTP Status: 400
  • Description: Field exceeds maximum length
  • Solution: Truncate to max length as per spec

VALID_004 - INVALID_ENUM_VALUE​

  • HTTP Status: 400
  • Description: Value not in allowed enum list
  • Solution: Use exact enum value from spec

VALID_005 - INVALID_DATE_FORMAT​

  • HTTP Status: 400
  • Description: Date not in required format
  • Solution: Use ISO 8601 format: YYYY-MM-DD

VALID_006 - DATE_IN_PAST​

  • HTTP Status: 400
  • Description: Date cannot be in the past
  • Solution: Use current or future date

VALID_007 - INVALID_CURRENCY_CODE​

  • HTTP Status: 400
  • Description: Currency code not valid ISO 4217
  • Solution: Use 3-letter codes: EUR, GBP, USD

VALID_008 - INVALID_COUNTRY_CODE​

  • HTTP Status: 400
  • Description: Country code not valid ISO 3166
  • Solution: Use 2-letter codes: GB, DE, FR

VALID_009 - INVALID_PHONE_NUMBER​

  • HTTP Status: 400
  • Description: Phone number format invalid
  • Solution: Include country code: +447777000001

VALID_010 - INVALID_JSON​

  • HTTP Status: 400
  • Description: Request body not valid JSON
  • Solution: Validate JSON syntax

System & Infrastructure​

SYSTEM_001 - INTERNAL_SERVER_ERROR​

  • HTTP Status: 500
  • Description: Unexpected server error
  • Solution: Retry with exponential backoff

SYSTEM_002 - SERVICE_UNAVAILABLE​

  • HTTP Status: 503
  • Description: Service temporarily unavailable
  • Solution: Check status page, retry later

SYSTEM_003 - RATE_LIMIT_EXCEEDED​

  • HTTP Status: 429
  • Description: Too many requests
  • Solution: Implement rate limiting, use backoff

SYSTEM_004 - GATEWAY_TIMEOUT​

  • HTTP Status: 504
  • Description: Request timeout
  • Solution: Retry or reduce request complexity

SYSTEM_005 - MAINTENANCE_MODE​

  • HTTP Status: 503
  • Description: System under maintenance
  • Solution: Check status page for updates

SYSTEM_006 - DEPRECATED_ENDPOINT​

  • HTTP Status: 410
  • Description: Endpoint no longer available
  • Solution: Migrate to new endpoint version

SYSTEM_007 - WEBHOOK_DELIVERY_FAILED​

  • HTTP Status: N/A (async)
  • Description: Webhook couldn't be delivered
  • Solution: Check webhook endpoint, return 2xx

SYSTEM_008 - INVALID_API_VERSION​

  • HTTP Status: 400
  • Description: API version not supported
  • Solution: Use supported version

SYSTEM_009 - REQUEST_TOO_LARGE​

  • HTTP Status: 413
  • Description: Request body exceeds size limit
  • Solution: Reduce request size, batch operations

SYSTEM_010 - IDEMPOTENCY_KEY_REUSED​

  • HTTP Status: 409
  • Description: Idempotency key used with different request
  • Solution: Use unique key per unique request

Quick resolution matrix​

SymptomLikely Error CodesFirst Check
Can't loginAUTH_001, AUTH_004API key headers
Can't create accountIDENTITY_001, AUTH_006KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. status, step-up
Card declinedCARD_003, TRANS_004Balance, limits
TransferTransfer A transaction that moves funds between instruments managed by Weavr. The source and destination instruments of a transfer transaction must be owned by the same identity. Transfers can be scheduled for future execution and can be performed in bulk operations. failedTRANS_001, ACCOUNT_001Instrument types, balance
403 ForbiddenAUTH_002, IDENTITY_001Permissions, verification
500 errorsSYSTEM_001Retry with backoff
Webhook issuesSYSTEM_007Endpoint returns 2xx

Error response examples​

Standard error response​

{
  "errorCode": "OWNER_IDENTITY_NOT_VERIFIED"
}

Validation error response​

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "mobile.number",
      "message": "Mobile number required"
    }
  ]
}

Rate limit response​

{
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

Best practices​

  1. Always log error codes - Essential for debugging
  2. Implement retry logic - For 5xx errors only
  3. Parse error details - Don't just check status code
  4. Use idempotency keys - Prevent duplicate operations
  5. Monitor patterns - Track common errors
  6. Test error paths - Include error handling in tests
  7. Document workarounds - Share solutions with team