Error Handling & Troubleshooting

A useful guide to understanding, handling, and resolving errors in the 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.

Quick error lookup

Having trouble? Jump directly to the solution:

Error Code	Common Cause	Quick Fix
UNAUTHORIZED	Invalid or missing API key	Check your API key in request headers
FORBIDDEN	Account or identity not verified, or in wrong state	Verify corporate identity or check account status
CHANNEL_NOT_REGISTERED	SMS/Auth factor not enrolled	Complete SMS enrolment process
OWNER_IDENTITY_NOT_VERIFIED	Corporate 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. not complete	Use Simulator API to verify (sandbox)
DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN	Account missing 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.	Upgrade account to 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. before funding
STEP_UP_REQUIRED	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). needed for operation	Complete step-up authentication

Understanding Weavr error responses

All Weavr API errors follow a consistent structure:

{
  "errorCode": "SPECIFIC_ERROR_CODE"
}

HTTP status codes

Status	Category	Common Scenarios
400	Bad Request	Invalid parameters, missing required fields
401	Unauthorized	Invalid API key, expired token
403	Forbidden	Insufficient permissions, wrong account state
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate resource, state conflict
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side issue, retry recommended
503	Service Unavailable	Temporary outage, maintenance

Common integration errors

Authentication errors

UNAUTHORIZED (401)

Problem: API key or authentication token is invalid or missing.

Symptom

# Example symptom: missing API key
curl -X POST "https://sandbox.weavr.io/multi/login_with_password" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": {"value": "pass"}}'

# Response
HTTP Status: 401
{"errorCode": "UNAUTHORIZED"}

Solution

# ✅ Include API key in all requests
curl -X POST "https://sandbox.weavr.io/multi/login_with_password" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": {"value": "pass"}}'

Checklist:
✓ API key included in api-key header
✓ API key is base64 encoded and valid
✓ Using correct environment (sandbox vs production).

FORBIDDEN (403)

Problem: User lacks permission or account is in wrong state.

Symptom

curl -X POST "https://sandbox.weavr.io/multi/managed_accounts" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{...}'

# Response
HTTP Status: 403
{"errorCode": "FORBIDDEN"}

Solution

Common Causes & Solutions:

1. Corporate not verified:

# Verify corporate in sandbox
curl -X POST "https://sandbox.weavr.io/simulate/api/corporates/YOUR_CORPORATE_ID/verify" \
  -H "programme-key: YOUR_API_KEY"

2. Email not verified:
   ✓ Complete email verification process

3. User not authenticated:
   ✓ Ensure valid auth token in Authorization: Bearer header
   ✓ Check token hasn't expired
   ✓ Stepped-up tokens expire after 5 minutes of inactivity

Enrolment & step-up errors

CHANNEL_NOT_REGISTERED

Problem: SMS authentication factor not enrolled.

Symptom

{
  "errorCode": "CHANNEL_NOT_REGISTERED"
}

Solution

Complete SMS Enrolment:

# Step 1: Initiate SMS enrolment
curl -X POST "https://sandbox.weavr.io/multi/authentication_factors/otp/SMS" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_TOKEN"

# Step 2: Verify with code (sandbox uses: 123456)
curl -X POST "https://sandbox.weavr.io/multi/authentication_factors/otp/SMS/verify" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"verificationCode": "123456"}'

Note: This enrolment is different from step-up challengesStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. - it's a one-time setup.

STEP_UP_REQUIRED

Problem: Operation requires Strong Customer Authentication (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).).

Symptom

{
  "errorCode": "STEP_UP_REQUIRED"
}

Solution

Complete Step-Up Flow:

# Step 1: Initiate challenge
curl -X POST "https://sandbox.weavr.io/multi/stepup/challenges/otp/SMS" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_TOKEN"

# Step 2: Verify challenge (sandbox: 123456)
curl -X POST "https://sandbox.weavr.io/multi/stepup/challenges/otp/SMS/verify" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"verificationCode": "123456"}'

# Token is now stepped-up for 5 minutes
# Retry your original operation

Operations requiring step-up:

• Creating users
• Creating 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.
• Issuing 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.
• Submitting Outgoing Wire TransfersWire Transfer A transaction that moves funds between accounts. An incoming wire transfer moves funds from a third-party bank account to a Weavr managed account, while an outgoing wire transfer moves funds from a Weavr managed account to a third-party bank account. Wire transfers require the managed account to have an assigned IBAN (for EUR) or sort code and account number (for GBP). and SendsSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary.

Business logic errors

OWNER_IDENTITY_NOT_VERIFIED

Problem: Corporate identity needs 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).

Symptom

{
  "errorCode": "OWNER_IDENTITY_NOT_VERIFIED"
}

Solution

Sandbox Quick Verification:

# Use Simulator API for instant verification
curl -X POST "https://sandbox.weavr.io/simulate/api/corporates/YOUR_CORPORATE_ID/verify" \
-H "programme-key: YOUR_API_KEY" \
-w "\nHTTP Status: %{http_code}\n"

# Expected: HTTP Status: 204

Production Process:

1. Complete email verification.
2. Complete mobile verification.
3. Trigger 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 via /corporates/kyb.
4. User completes 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. UI component.
5. Wait for webhook notification of approval.
6. Corporate can now create accounts/cards.

DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN

Problem: 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. (or sort code and account number for GBP) in order to fund the account.

Symptom

{
  "errorCode": "DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN"
}

Solution

Upgrade Account to 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.:

# Upgrade managed account
curl -X POST "https://sandbox.weavr.io/multi/managed_accounts/YOUR_ACCOUNT_ID/iban" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{}'

# Response includes IBAN and BIC
{
"accountId": "115134292391559240",
"bankDetails": {
  "iban": "GB33CLRB04066011000001",
  "bic": "CLRBGB22"
},
"state": "ACTIVE"
}

Note: 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. upgrade may be async - check state field.

Data validation errors

INVALID_ENUM_VALUE

Problem: Using incorrect enum values (singular vs plural).

Symptom

{
  "errorCode": "INVALID_ENUM_VALUE"
}

Solution

Use Correct Enum Values:

// ❌ Wrong - singular
{
"source": {
  "type": "managed_account",  // Wrong!
  "id": "123"
}
}

// ✅ Correct - plural
{
"source": {
  "type": "managed_accounts",  // Correct!
  "id": "123"
}
}

Common Enum Corrections:

• managed_account → managed_accounts
• managed_card → managed_cards
• Always check API spec for exact enum values

Testing best practices

Test in sequence

Many operations have dependencies:

1. Create corporate → 2. Set root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. password → 3. Verify root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. email and mobile → 4. Verify corporate → 5. Login → 6. Step-up (if not already) → 7. Create account

Breaking the chain causes errors. Test each step individually.

Rate limiting & retry strategy

Rate limits

• Sandbox: 1000 requests per minute per EmbedderEmbedder A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers.
• Production: Different limits apply (contact support for details)
• Step-up: 3 attempts per challenge
• Login: 10 attempts per hour per user

Retry strategy

Only retry requests that fail due to temporary server issues:

• Retry for: 5xx errors (500, 503) - server-side problems
• Don't retry: 4xx errors (400, 401, 403, 409) - client-side issues that won't resolve
• Use exponential backoff: Wait longer between each retry attempt

Environment-specific issues

Sandbox vs Production

Issue	Sandbox	Production
Verification codes	Always 123456	Real SMS/email
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	Simulator API instant	Full documentation required
Card numbers	Test cards only	Real card issuance
Rate limits	1000 requests/min per EmbedderEmbedder A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers.	Different limits apply

Simulator API authentication

Simulator API uses different header:

# ❌ Wrong - Multi API header
-H "api-key: YOUR_API_KEY"

# ✅ Correct - Simulator API header
-H "programme-key: YOUR_API_KEY"

Getting help

Before contacting support

1. Check HTTP status code - Identifies error category
2. Read error message - Often indicates the specific fix required
3. Review this guide - Common errors documented
4. Test in isolation - Simplify to minimum reproduction
5. Collect details:
   • Request ID (from headers)
   • Timestamp
   • Full request/response
   • Account/corporate IDs

Support channels

• Documentation: docs.weavr.io
• API Reference: api.weavr.io
• Support Portal: support.weavr.io
• Status Page: weavr.statuspage.io

Next steps

• Authentication Guide → - Deeper dive into auth flows
• Quick Start Guide → - Working implementation example
• API Reference → - Complete endpoint documentation