Error codes reference

Reference of Weavr API error codes with descriptions and solutions.

Docs-only grouping IDs

The AUTH_001, CARD_001, and similar identifiers used as section headings on this page are grouping IDs for documentation navigation only. The Weavr API returns the uppercase snake_case error code shown in each heading (for example, UNAUTHORIZED, INSUFFICIENT_BALANCE) in the errorCode field. Parse that field, not the docs-only grouping ID.

Error code categories

Error codes are grouped by functional area for easier navigation:

Authentication & Authorization
Identity & KYC/KYB
Managed Accounts
Managed Cards
Transactions
Validation & Data
System & Infrastructure

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 the user has the required role for the operation, and check the 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: Enroll 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 complexity requirements
Solution: Passwords must be 8 to 30 characters, contain at least one uppercase letter, one lowercase letter, one number, and one special character, and differ from the user's last 5 passwords. See password complexity for the canonical rules and the POST /passwords/validate endpoint you can call to pre-check a password from your server.

`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 enrollment 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-either by Weavr (for compliance or security reasons) or by your own administrator via the API
Solution: If you did not initiate the suspension, contact Weavr support

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 a unique idempotency-ref header per request

`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: the same idempotency-ref was reused with a different request payload
Solution: generate a unique idempotency-ref per distinct request, or repeat the original request unchanged. See Idempotent requests.

Quick resolution matrix

Symptom	Likely error codes	First check
Can't login	`AUTH_001`, `AUTH_004`	API key headers
Can't create account	`IDENTITY_001`, `AUTH_006`	KYB status, step-up
Card declined	`CARD_003`, `TRANS_004`	Balance, limits
Transfer failed	`TRANS_001`, `ACCOUNT_001`	Instrument types, balance
403 Forbidden	`AUTH_002`, `IDENTITY_001`	Permissions, verification
500 errors	`SYSTEM_001`	Retry with backoff
Webhook issues	`SYSTEM_007`	Endpoint 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

Always log error codes - Essential for debugging
Implement retry logic - For 5xx errors only
Parse error details - Don't just check status code
Use the idempotency-ref header - Prevent duplicate operations on supported endpoints
Monitor patterns - Track common errors
Test error paths - Include error handling in tests
Document workarounds - Share solutions with team

Error code categories​

Authentication & Authorization​

AUTH_001 - UNAUTHORIZED​

AUTH_002 - FORBIDDEN​

AUTH_003 - TOKEN_EXPIRED​

AUTH_004 - INVALID_CREDENTIALS​

AUTH_005 - ACCOUNT_LOCKED​

AUTH_006 - STEP_UP_REQUIRED​

AUTH_007 - CHANNEL_NOT_REGISTERED​

AUTH_008 - INVALID_VERIFICATION_CODE​

AUTH_009 - PASSWORD_POLICY_VIOLATION​

AUTH_010 - SESSION_EXPIRED​

Identity & KYC/KYB​

IDENTITY_001 - OWNER_IDENTITY_NOT_VERIFIED​

IDENTITY_002 - EMAIL_NOT_VERIFIED​

IDENTITY_003 - MOBILE_NOT_VERIFIED​

IDENTITY_004 - DUPLICATE_EMAIL​

IDENTITY_005 - DUPLICATE_IDENTITY​

IDENTITY_006 - KYB_REJECTED​

IDENTITY_007 - INVALID_COMPANY_TYPE​

IDENTITY_008 - INVALID_COUNTRY​

IDENTITY_009 - ABANDONED_USER​

IDENTITY_010 - USER_SUSPENDED​

Managed accounts​

ACCOUNT_001 - INSUFFICIENT_BALANCE​

ACCOUNT_002 - DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN​

ACCOUNT_003 - ACCOUNT_BLOCKED​

ACCOUNT_004 - CURRENCY_MISMATCH​

ACCOUNT_005 - DUPLICATE_ACCOUNT​

ACCOUNT_006 - INVALID_PROFILE_ID​

ACCOUNT_007 - ACCOUNT_CLOSED​

ACCOUNT_008 - IBAN_ALREADY_ASSIGNED​

ACCOUNT_009 - STATEMENT_NOT_READY​

ACCOUNT_010 - EXCEEDS_ACCOUNT_LIMIT​

Managed cards​

CARD_001 - CARD_BLOCKED​

CARD_002 - CARD_EXPIRED​

CARD_003 - INSUFFICIENT_CARD_BALANCE​

CARD_004 - EXCEEDS_SPENDING_LIMIT​

CARD_005 - INVALID_PIN​

CARD_006 - CARD_NOT_ACTIVATED​

CARD_007 - DUPLICATE_CARD​

CARD_008 - INVALID_CARD_MODE​

CARD_009 - BILLING_ADDRESS_REQUIRED​

CARD_010 - NAME_ON_CARD_INVALID​

Transactions​

TRANS_001 - INVALID_INSTRUMENT_TYPE​

TRANS_002 - SOURCE_INSTRUMENT_NOT_FOUND​

TRANS_003 - DESTINATION_INSTRUMENT_NOT_FOUND​

TRANS_004 - INVALID_AMOUNT​

TRANS_005 - EXCEEDS_TRANSACTION_LIMIT​

TRANS_006 - DUPLICATE_TRANSACTION​

TRANS_007 - TRANSFER_NOT_ALLOWED​

TRANS_008 - INVALID_BENEFICIARY​

TRANS_009 - TRANSACTION_DECLINED​

TRANS_010 - REVERSAL_NOT_ALLOWED​

Validation & Data​

VALID_001 - MISSING_REQUIRED_FIELD​

VALID_002 - INVALID_FIELD_FORMAT​

VALID_003 - FIELD_TOO_LONG​

VALID_004 - INVALID_ENUM_VALUE​

VALID_005 - INVALID_DATE_FORMAT​

VALID_006 - DATE_IN_PAST​

VALID_007 - INVALID_CURRENCY_CODE​

VALID_008 - INVALID_COUNTRY_CODE​

VALID_009 - INVALID_PHONE_NUMBER​

VALID_010 - INVALID_JSON​

System & Infrastructure​

SYSTEM_001 - INTERNAL_SERVER_ERROR​

SYSTEM_002 - SERVICE_UNAVAILABLE​

SYSTEM_003 - RATE_LIMIT_EXCEEDED​

SYSTEM_004 - GATEWAY_TIMEOUT​

SYSTEM_005 - MAINTENANCE_MODE​

SYSTEM_006 - DEPRECATED_ENDPOINT​

SYSTEM_007 - WEBHOOK_DELIVERY_FAILED​

SYSTEM_008 - INVALID_API_VERSION​

SYSTEM_009 - REQUEST_TOO_LARGE​

SYSTEM_010 - IDEMPOTENCY_KEY_REUSED​

Quick resolution matrix​

Error response examples​