Error Handling & Troubleshooting

A useful guide to understanding, handling, and resolving errors in the Weavr Multi 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 KYB not complete	Use Simulator API to verify (sandbox)
`DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN`	Account missing IBAN	Upgrade account to IBAN before funding
`STEP_UP_REQUIRED`	SCA 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
Solution

# 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"}

# ✅ 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
Solution

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

Common Causes & Solutions:

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"

Email not verified:
✓ Complete email verification process
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
Solution

{
  "errorCode": "CHANNEL_NOT_REGISTERED"
}

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 challenges - it's a one-time setup.

STEP_UP_REQUIRED

Problem: Operation requires Strong Customer Authentication (SCA).

Symptom
Solution

{
  "errorCode": "STEP_UP_REQUIRED"
}

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 Accounts
Issuing Managed Cards
Submitting Outgoing Wire Transfers and Sends

Business logic errors

OWNER_IDENTITY_NOT_VERIFIED

Problem: Corporate identity needs KYB verification (and email/mobile verification).

Symptom
Solution

{
  "errorCode": "OWNER_IDENTITY_NOT_VERIFIED"
}

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:

Complete email verification
Complete mobile verification
Trigger KYB process via /corporates/kyb
User completes KYB UI component
Wait for webhook notification of approval
Corporate can now create accounts/cards

DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN

Problem: Account needs IBAN (or sort code and account number for GBP) in order to fund the account.

Symptom
Solution

{
  "errorCode": "DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN"
}

Upgrade Account to IBAN:

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

Data validation errors

INVALID_ENUM_VALUE

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

Symptom
Solution

{
  "errorCode": "INVALID_ENUM_VALUE"
}

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:

Create corporate → 2. Set root user password → 3. Verify 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 Embedder
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
KYB process	Simulator API instant	Full documentation required
Card numbers	Test cards only	Real card issuance
Rate limits	1000 requests/min per Embedder	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

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

Support channels

Documentation: docs.weavr.io
API Reference: weavr-multi-api.redoc.ly
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

Quick error lookup​

Understanding Weavr error responses​

HTTP status codes​

Common integration errors​

Authentication errors​

UNAUTHORIZED (401)​

FORBIDDEN (403)​

Enrolment & step-up errors​

CHANNEL_NOT_REGISTERED​

STEP_UP_REQUIRED​

Business logic errors​

OWNER_IDENTITY_NOT_VERIFIED​

DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN​

Data validation errors​

INVALID_ENUM_VALUE​

Testing best practices​

Test in sequence​

Rate limiting & retry strategy​

Rate limits​

Retry strategy​

Environment-specific issues​

Sandbox vs Production​

Simulator API authentication​

Getting help​

Before contacting support​

Support channels​

Next steps​