Skip to main content

Error handling and troubleshooting

A guide to understanding, handling, and resolving errors when calling our API. This page covers API-level errors - for SDK-specific issues, see the SDK-specific resources following.

Looking for SDK troubleshooting?​

This page focuses on API error responses. Each SDK has its own error reference and, where applicable, framework-specific troubleshooting:

For a full index of error codes returned by the API, see the error codes reference.

Quick error lookup​

Having trouble? Jump directly to the solution:

Error codeCommon causeQuick fix
UNAUTHORIZEDInvalid or missing API keyCheck your API key in request headers
FORBIDDENAccount or identity not verified, or in wrong stateVerify corporate identity or check account status
CHANNEL_NOT_REGISTEREDSMS/Auth factor not enrolledComplete SMS enrollment process
OWNER_IDENTITY_NOT_VERIFIEDCorporate 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 completeUse Simulator API to verify (sandbox)
DENIED_ACCOUNT_NOT_UPGRADED_TO_IBANAccount 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_REQUIREDSCASCA 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 operationComplete step-up authentication

Understanding Weavr error responses​

All Weavr API errors follow a consistent structure:

{
  "errorCode": "SPECIFIC_ERROR_CODE"
}

HTTP status codes​

StatusCategoryCommon scenarios
400Bad RequestInvalid parameters, missing required fields
401UnauthorizedInvalid API key, expired token
403ForbiddenInsufficient permissions, wrong account state
404Not FoundResource doesn't exist
409ConflictDuplicate resource, state conflict
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side issue, retry recommended
503Service UnavailableTemporary outage, maintenance

Common integration errors​

Authentication errors​

UNAUTHORIZED (401)​

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

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

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

FORBIDDEN (403)​

Problem: User lacks permission for the operation (based on their role) or account is in wrong state.

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

Enrollment & step-up errors​

CHANNEL_NOT_REGISTERED​

Problem: SMS authentication factor not enrolled.

{
  "errorCode": "CHANNEL_NOT_REGISTERED"
}

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).).

{
  "errorCode": "STEP_UP_REQUIRED"
}

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).

{
  "errorCode": "OWNER_IDENTITY_NOT_VERIFIED"
}

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.

{
  "errorCode": "DENIED_ACCOUNT_NOT_UPGRADED_TO_IBAN"
}

Data validation errors​

INVALID_ENUM_VALUE​

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

{
  "errorCode": "INVALID_ENUM_VALUE"
}

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 account
  • 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 versus production​

IssueSandboxProduction
Verification codesAlways 123456Real 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. processSimulator API instantFull documentation required
Card numbersTest cards onlyReal card issuance
Rate limits1000 requests/min per accountDifferent limits apply

Simulator API authentication​

Simulator API uses different header:

# ❌ Wrong - Weavr 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​

Next steps​