Skip to main content

Error Codes Reference

Reference of Weavr Multi 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 SCA/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 & KYC/KYB​

IDENTITY_001 - OWNER_IDENTITY_NOT_VERIFIED​

  • HTTP Status: 403
  • Description: Corporate/consumer needs KYC/KYB verification (and email/mobile verification in production)
  • Solution: Complete KYB 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: KYB 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 accounts​

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 IBAN 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 account/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 IBAN
  • Solution: Use existing IBAN 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 cards​

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 mode)
  • Solution: Transfer 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 card 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: Transfer between these instruments not allowed
  • Solution: Check transfer rules and restrictions

TRANS_008 - INVALID_BENEFICIARY​

  • HTTP Status: 400
  • Description: Beneficiary details invalid/incomplete
  • Solution: Provide complete beneficiary 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_006KYB status, step-up
Card declinedCARD_003, TRANS_004Balance, limits
Transfer 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