Appendix
What is changing?
We're updating the error codes for the Embedded Payments API. We're introducing granular, dedicated error codes to replace shared codes that currently carry multiple messages (such as, expanding code 11100 into 11100 through 11105).
Why are things changing?
To improve clarity and support the long-term scalability of the Embedded Payments platform, we are replacing shared, multi-purpose codes with dedicated, granular error messaging.
When will the changes be effective?
The changes will be effective Thursday, February 4, 2027. Allow enough time to implement and test your updates before the effective date.
Do these changes affect me?
If you don't use automated error handling based on 5-digit error codes, you don't need to take any action.
What do I need to do to be ready?
Review your error-handling logic for the affected codes. We're introducing the following changes:
- New codes: New error codes for additional scenarios. Refer to the following table for the new codes: 11144, 11403, 11406, 11540, 11614, 11620
- Updated codes: Existing error codes with updated descriptions. Refer to the following table for the updated codes: 11011, 11122, 11129, 11709, 11710
- Remapped codes: Scenarios that previously returned one code will now return a different code. Refer to the following table for the remapped codes: 10105, 10199, 10233, 11312, 13001, 13005
- Removed codes: Deprecated error codes we'll no longer be return. Refer to the following table for the removed codes: 11312, 13001, 13005
Note: You can safely add handling for the new codes ahead of time. You do not need to wait until the release.
Action |
Current Code |
New Code |
Breaking Change |
Error Code Reasoning |
|---|---|---|---|---|
NEW |
11144 |
No |
Unknown BIC in routing table |
|
NEW |
11403 |
No |
Ledger balance must be zero before closing account |
|
NEW |
11406 |
No |
Update is not permitted for account type |
|
NEW |
11540 |
No |
Charge bearer code invalid |
|
NEW |
11614 |
No |
Reason provided as narrative |
|
NEW |
11620 |
No |
BIC identifier invalid or missing |
|
UPDATED |
11011 |
No |
Updated to: Creditor account currency is invalid or missing. |
|
UPDATED |
11122 |
No |
Updated to: Payment transferred and not tracked. |
|
UPDATED |
11129 |
No |
Updated to: Return after investigation, no remediation. |
|
UPDATED |
11709 |
No |
Updated to: Final response/tracking is recalled as mandate is cancelled. |
|
UPDATED |
11710 |
No |
Updated to: Cancellation not accepted due to regulatory rules. |
|
REMAPPED |
11312 |
11540 |
Yes |
Charge bearer code invalid |
REMAPPED |
13001 |
11614 |
Yes |
Reason provided as narrative |
REMAPPED |
13005 |
11144 |
Yes |
BIC identifier invalid or missing |
REMAPPED |
10105 |
11406 |
Yes |
The account category provided is not allowed for the given program |
REMAPPED |
10105 |
11406 |
Yes |
The field provided is not allowed for the given account category |
REMAPPED |
10105 |
11004 |
Yes |
The account is already closed |
REMAPPED |
10105 |
11406 |
Yes |
This operation only supports accounts with categories: {categories} |
REMAPPED |
10199 |
11403 |
Yes |
The account cannot be closed due to having an outstanding balance of {amount}. Account balance must be 0 to allow closure. |
REMAPPED |
10233 |
10104 |
Yes |
Field must not be null or blank (mandatory element missing) |
REMAPPED |
10233 |
10104 |
Yes |
MISSING_LABEL – label must not be null or blank |
REMAPPED |
10233 |
10104 |
Yes |
Client ID is missing |
REMOVED |
11312 |
Yes |
Removed. Use 11540 instead. |
|
REMOVED |
13001 |
Yes |
Removed. Use 11614 instead. |
|
REMOVED |
13005 |
Yes |
Removed. Use 11144 instead. |
|
Are these changes backward compatible?
No. These changes aren't backward compatible, as we're replacing shared codes with dedicated, granular codes.
Where can you find more details? Who can you contact?
Contact the Client Solutions team for questions or support.