Error Handling

Comprehensive guide to handling errors across the customer lifecycle flows.

Error Response Format

All API errors follow a consistent format:

HTTP Status Codes

Registration Errors

Password Mismatch (400)

Solution: Ensure password and matchingPassword fields contain identical values.

Invalid Categorization (400)

Solution:

1. Call GET /categorization/hierarchy/{tenantId} to get available options
2. Check mandatoryKeys for the feature
3. Ensure all mandatory keys are provided
4. Validate values against allowedValues

Tenant Access Denied (403)

Organization Already Exists (409)

Solution: Use a unique registration number or retrieve the existing organization.

Authentication Errors

Invalid Credentials (401)

Solution: Verify username (email) and password are correct.

Account Locked (401)

Solution: Wait for lockout period to expire (30 minutes) or contact support.

Token Expired (401)

Solution: Obtain a new token via the session creation endpoint.

Verification Errors

Insufficient Permission (403)

Solution: Use an account with COMPLIANCE_OFFICER or ADMIN_USER role.

Activation Errors

Missing Consents (400)

Solution: Accept all missing consents using the provided acceptUrl endpoints.

Not Verified (422)

Solution: Wait for verification to be approved before attempting activation.

Missing ADMIN_USER Role (400)

Solution: Ensure the first employee added has the ADMIN_USER role.

Transaction Errors

Insufficient Balance (400)

Solution: Top up the wallet or reduce the transaction amount.

Limit Exceeded (400)

Solution: Wait for limit reset or use a smaller amount.

Beneficiary Not Found (404)

Solution: Add the beneficiary using the beneficiaries endpoint before attempting the transfer.

Troubleshooting Checklist

Registration Issues

• Valid email format
• Password meets requirements (8+ chars, mixed case, numbers, special)
• password matches matchingPassword
• Valid tenant ID in header
• Categorization values match allowed values

Authentication Issues

• Correct username (email)
• Correct password
• Valid tenant key and secret
• Account not locked
• Token not expired

Activation Issues

• Verification status is APPROVED
• All three consents accepted (Terms, Privacy, Data Processing)
• Customer not already active
• For B2B: At least one employee with ADMIN_USER role

Transaction Issues

• Wallet is ACTIVE
• Sufficient balance
• Within transaction limits
• Beneficiary exists and is active
• Valid payment consent in place

Error Handling Best Practices

1. Parse error responses - Always check the data object for detailed information
2. Handle retries carefully - Don’t retry on 400/403/422 errors
3. Log error details - Store code, message, and data for debugging
4. Show user-friendly messages - Map technical errors to user-friendly text
5. Implement exponential backoff - For 429 and 500 errors