Error Codes
Error Codes
The Convera API Suite uses a standardized list of error codes to help diagnose issues from data validation to payment processing.
General API Error Codes
Below are the possible error codes that are returned in the HTTP response when submitting an API request.
While great care has been taken to reduce the number of unhandled exceptions, it is possible to encounter a scenario that does not have a specific error code associated with it. If you encounter this scenario, please contact the Convera customer support team so we can work to get the error resolved and associated with an error code.
Error Code | Error Description | Conditions | Actions to Take |
---|---|---|---|
1000 | Generic web service error | An unhandled exception has occurred | Resend request 2-3 times over a 5 minute interval. If issue persists, please contact the Convera customer support team |
1001 | Access denied | Client certificate or API token cannot be verified, or a request has been made to unauthorized resources | Ensure proper authorization is attached to request, or request access to resource |
1003 | Required field validation error | A required data field was either not included or was passed with a null or empty string value | Populate field indicated in error message e.g. 1003: paymentMethod |
1004 | Conditional field validation error | A conditional field was either not included or was passed with a null or empty string value | Refer to the API Reference for more information on conditional field requirements |
1005 | Input field value validation error | Value is outside the bounds of syntax or format validation e.g. specifying a string value in an amount field | Refer to the API Reference for more information on field datatype and syntax expectations |
1006 | Unexpected field submitted | Request contains a field that is not part of the API resource model | Remove fields not specified in the API resource model |
1007 | Defined limit exceeded | Limit has been exceeded for resources with a maximum e.g. number of webhook endpoints | Delete or update existing resources with desired information |
1100 | Generic web service error | An unhandled exception has occurred | Resend request 2-3 times over a 5 minute interval. If issue persists, please contact the Convera customer support team |
1101 | Resource not found | A resource was requested but not found | Ensure resources are created in the API before attempting to utilize them |
1102 | Invalid quote | Quote not generated for order commit | Establish a valid Quote ID before attempting to commit an order |
1103 | Quote expired | Previously generated quote ID has expired and must be regenerated prior to order commit | Regenerate quote ID for order |
1104 | Payment update not supported | Attempted update of payment that has been accepted as Created | Delete payment from batch and create a new payment with requested updates |
1105 | Payment cannot be cancelled | Attempted deletion of payment in either status notAccepted or past Created status | Payments that have entered workflow cannot be cancelled via API and may be irrevocable. Please call Convera customer support for more information. |
1107 | Customer cannot be found | Customer is not registered with the Convera API Suite, or the provided customer ID is invalid | Register customer ID with Convera or provide valid customer ID |
1108 | Each settlement currency may only be specified once when committing a batch | A settlement currency is specified more than once in a commit batch request | Remove duplicate instances of settlement currencies in a commit batch request |
1109 | Payment settlement currency cannot be determined | Customer does not have a default settlement account assigned, or the settlement currency has not been specified in request | Configure customer with default settlement currency, or provide settlement currency in request |
1110 | Extra settlement currency provided when committing a batch | A settlement currency not previously provided is now being specified when committing a batch | Ensure payment settlement currencies match settlement currencies of batch commit |
1111 | Insufficient holding balance for settlement | Customer is attempting to settle using a holding balance that cannot cover the cost of the transaction | Fund holding balance with additional funds, or change settlement method |
1112 | Currency not supported | Currency specified in the request is not supported by Convera | Specify a currency supported by Convera. |
1113 | Payments cannot be added to a committed or deleted batch | Attempted addition of payments to a batch in Committed or Cancelled status | Create a new batch for additional payments |
1114 | Currency pair must be unique | A quote is being requested for the same currency pair more than once in a single request | Submit unique currency pairs in a request |
1115 | Unsupported currency and payment method combination | Payment has been submitted with a currency and payment method combination that is not supported by Convera | Specify a currency and payment method combination that is supported by Convera. |
1116 | Payment method invalid or not supported | Payment method specified during payment submission is invalid or not supported | Specify a valid payment method when submitting a payment |
1117 | Remittance type invalid or not supported | Remittance type specified during payment submission was invalid or is not supported | Specify a valid remittance type when submitting a payment |
1118 | Remittance type mismatch | Remittance type specified is supported, but may not be valid for specified payment currency, method, region, beneficiary type, or number of addenda records | Verify the payment is utilizing the correct remittance type |
1120 | Primary webhook cannot be deleted | Primary webhook cannot be deleted when multiple webhooks exist | Delete secondary webhooks before attempting to delete primary webhook |
1206 | Batch is empty | Attempt to quote or commit an empty batch | Submit at least one valid payment before quoting and committing the batch |
1207 | Amount is fixed on a currency that is inconsistent with similar payments | A payment has a fixed amount specified that is different than others payments of the same currency pair | Ensure all payments of a currency pair are submitted with a fixed amount, or none are submitted with a fixed amount |
1209 | Total amount of the order exceeds the customers debit limit | Order booked that exceeds customers e-debit account limit | Change settlement method, or change the order amount |
1210 | Customer is not setup to use settlement method | Specified settlement method not configured for customer | Change settlement method or contact Convera for configuration |
1211 | Minimum amount not met | Specified field does not meet required minimum amount for processing. | Increase amount for processing or specify different currency. |
1212 | Maximum limit exceeded | Specified field exceeds allowed amount for payment method and currency combination. | Specify a different amount, payment method, or currency. |
1213 | Currency not holding enabled | Specified currency not supported as holding-enabled | Specify a different currency |
1217 | Validation error when generating instructions for bank | Field format or contents validation error during workflow | Address failure reason or contact Convera customer support team for investigation |
1218 | Error occurred when generating payment instructions for bank | Error occurred when generating payment instructions for bank | Contact Convera customer support team for investigation |
1219 | Error occurred when committing the batch | Error occurred when committing the batch | Contact Convera customer support team for investigation |
1222 | Error in FAB service | Input field validation failed for request | Ensure FAB requests meet input field validation requirements |
1223 | Invalid country code | Country code does not adhere to ISO 3166 alpha-2 syntax or country is not supported. | Ensure country code is valid and in the proper format. |
1224 | Multiple payments added to batch where not allowed | More than one payment submitted in a Dodd-Frank or Draft payment batch | Create a new batch for additional payments |
1225 | Payment is non-Dodd-Frank payment | Attempt to call disclosure API for a non-Dodd-Frank payment | Submit a Dodd-Frank payment before submitting Disclosure request |
1226 | Invalid SWIFT code format | SWIFT code provided is not either 8 or 11 characters alphanumeric | Provide a valid SWIFT code format |
1229 | CAML payments can not include a Postal Installation. | For payments into or out of Canada, PO Boxes are not allowed. Please see Canadian Payments for conditions. | Remove PO box from any payment address fields. |
1230 | Duplicate resource not allowed - batch | Batch IDs must be unique across the customer account. | Submit a unique batch ID across the customer ID. |
Find-A-Bank Error Codes
The error codes below are specific to the Find-A-Bank Resource APIs.
Error Code | Error Description |
---|---|
Err1011 | The country(county/code/country name provided is invalid |
Err1012 | Your entered IBAN is not valid. Try again or search for a bank |
Err1018 | Mandatory fields missing in the search. |
Err1019 | If no SWIFT Code or Bank Routing Code (e.g. Sort Code, BLZ, BSB Code, Fedwire etc.) is provided, then both Bank Name and City are mandatory. |
Err1020 | The country identifier in the IBAN provided does not match the provided Bank Country. |
Err1022 | The country identifier in the IBAN provided does not match any country. |
Err1024 | IBAN length is not valid. |
Err1026 | Invalid checksum, the validation calculation that checks if the routing destination and account number match has failed. |
Err1029 | The account number part of the IBAN is invalid. |
Err1031 | IBAN is currently not supported by banks in the bank country you provided. |
Err1032 | Currency is invalid. |
Err1033 | Unauthorized Request. |
Err1034 | The bank branch identifier entered within the IBAN could not be found in the global bank database |
Err1035 | At least one of the following must be provided, Bank Country plus: 1. SWIFT Code 2. Bank Routing Code (e.g. Sort code, BLZ, BSB code, Fedwire etc.). 3. Bank name and City (Street address may also be provided to further filter the results) |
Err1036 | The Search includes invalid values. Please check your search parameters. |
Err1037 | Authorization connection exception |
Exp1000 | An exception occurred. Please contact Convera. |
War1014 | Too many records found; please provide additional information to further refine the search and reduce the number of results. |
War1015 | No records found that match the details provided. |
NOC Codes
Notice of Change (NOC) codes indicated errors that have been generated by a receiving bank that are destined to the payment originator. These codes typically indicate that a portion of the requested bank information is now invalid and must be changed to prevent future payment rejections.
NOC Code | Code Description | Condition |
---|---|---|
C01 | Incorrect bank account number | Incorrect bank account number or format |
C02 | Incorrect transit/routing number | Once valid transit/routing number must be changed |
C03 | Incorrect transit/routing number and bank account number | Once valid transit/routing number must be changed and causes a change to bank account number structure |
C05 | Incorrect payment code | Entry posted to demand account should contain savings payment codes or vice-versa |
C06 | Incorrect bank account number and transit code | Bank account number must be changed and payment code should indicate posting to another account type (demand/savings) |
C07 | Incorrect transit/routing number, bank account number, and payment code | Changes required in three fields indicated |
Rejection Codes
Payments can be rejected at the point of message transmission, or shortly thereafter, if there is an unforeseen issue. Typically, this can be a data integrity issue (e.g., special characters present some banks cannot process), or an improperly structured identifier, like an IBAN or local routing code.
Some of these rejection codes have standard messages, but others are returned with descriptive information from our banking partners that require further investigation by Convera staff.
Error Code | Error Description | Actions to Take |
---|---|---|
ER001 | Charge bearer is absent | Beneficiary may have not responded to bank to accept charges for payment. Contact beneficiary. |
ER002 | Beneficiary type is missing or invalid | Supply the correct beneficiary type and resubmit the payment |
ER003 | Change bearer is invalid | |
ER004 | Purpose of payment is missing | Supply purpose of payment and resubmit the payment |
ER005 | Tax ID is missing | Supply tax ID and resubmit the payment |
ER006 | Country is absent | Supply country and resubmit the payment |
ER007 | Country is invalid | Validate country is valid and resubmit the payment |
ER008 | Field 23b on 103 is absent | Internal error - please contact Convera |
ER009 | Field 23b on 103 is invalid | Internal error - please contact Convera |
ER010 | BIC is absent for MT202 | Supply BIC and resubmit the payment |
ER011 | Payment date is missing | Internal error - please contact Convera |
ER012 | Amount is invalid | Validate amount and resubmit payment |
ER013 | Payment ID is missing | Internal error - please contact Convera |
ER014 | Payment ID is invalid | Internal error - please contact Convera |
ER015 | Field 57 is invalid | Internal error - please contact Convera |
ER016 | Currency is invalid for this debiting bank account | Internal error - please contact Convera |
ER017 | Debiting bank account number is missing | Internal error - please contact Convera |
ER018 | Mandatory data for field 5oa/50k on 103/202 is absent | Internal error - please contact Convera |
ER019 | Account with institution is invalid | Validate bank account number and routing information and resubmit payment |
ER020 | Payment date must not be more than 7 days in the future | Internal error - please contact Convera |
ER021 | Intermediary institution is invalid | Validate intermediary bank information and resubmit payment |
ER022 | Payment date must be within the past 30 days | Internal error - please contact Convera |
ER023 | Payment date must not be more than 30 days in the future | Internal error - please contact Convera |
ER024 | Payment date must not be more than 60 days in the future | Internal error - please contact Convera |
ER025 | Debtor client number is missing | Internal error - please contact Convera |
ER026 | Debtor name is missing | Internal error - please contact Convera |
ER027 | Debtor street address is missing | Internal error - please contact Convera |
ER028 | Debtor town name is missing | Internal error - please contact Convera |
ER029 | Debtor country is missing | Internal error - please contact Convera |
ER030 | Debtor country is missing or invalid for this debiting bank account | Internal error - please contact Convera |
ER031 | Beneficiary name is missing | Internal error - please contact Convera |
ER032 | Beneficiary town name is missing | Validate beneficiary city or town and resubmit payment |
ER033 | Beneficiary post code is missing | Validate beneficiary zip or postal code and resubmit payment |
ER034 | Beneficiary country is missing or is not valid for this channel | Validate beneficiary country code and resubmit payment |
ER035 | Beneficiary account number is missing or is not a valid length | Validate beneficiary account number and resubmit payment |
ER036 | Beneficiary bank name is missing | Validate beneficiary bank name and resubmit payment |
ER037 | Beneficiary bank routing code is missing or is not a valid length | Validate beneficiary bank routing code and resubmit payment |
ER038 | Beneficiary bank SWIFT code is missing or is not a valid length | Validate beneficiary bank SWIFT code and resubmit payment |
ER039 | Beneficiary bank country is missing | Validate beneficiary bank country code and resubmit payment |
ER040 | Beneficiary bank country is not valid for this channel | Validate beneficiary bank country code and resubmit payment |
ER041 | Beneficiary street address is missing | Validate beneficiary address line 1 and resubmit payment |
ER995 | Rejected by GPG | Internal error - please contact Convera. The code will be accompanied by one of the following reasons: Invalid or insufficient payment details , Invalid bank code , Invalid RUT code , Incorrect name format , Amount is too small to process |
ER997 | Instruction ID is not unique | Internal error - please contact Convera |
ER998 | Account not configured in GPG | Internal error - please contact Convera |
NARR | Custom message from bank | Take action depending on message from bank |
SWF_ERROR: T28 | SWIFT BIC is not a valid destination | Correct SWIFT BIC code and resubmit payment |
SWF_ERROR: T45 | Invalid non-SWIFT BIC | Correct SWIFT BIC code and resubmit payment |
SWF_ERROR: T29 | SWIFT BIC contains an invalid branch code | Correct SWIFT BIC code and resubmit payment |
Return Codes
Return codes are given by the API when a payment encounters scenarios where the payment cannot be applied to the beneficiary account.
Return Code | Code Description | Additional Information |
---|---|---|
RTN01 | Account closed | |
RTN02 | No account or unable to locate account | |
RTN03 | Account number and beneficiary do not match | |
RTN04 | Invalid account number | |
RTN05 | Invalid beneficiary name | |
RTN06 | Beneficiary declined funds; unable to contact beneficiary | |
RTN07 | Beneficiary did not claim funds | |
RTN08 | Invalid or insufficient payment details | |
RTN09 | Invalid or insufficient beneficiary bank branch details | |
RTN10 | Invalid routing code | |
RTN11 | Invalid SWIFT code | |
RTN12 | Incorrect currency | |
RTN13 | Rejected per internal policy (Compliance) | The payment returns to us due to it being rejected by bank’s compliance – either our correspondent bank has made a compliance-based decision to not process the payment, or this payment is not compliant with intermediary or beneficiary banks. The banks typically also inform us whether the payment is reported to OFAC. |
RTN14 | Per recall request | If a reversal/recall for the payment was initiated, on successful recall it will be returned stating this reason. |
RTN15 | Bank endorsement missing | Very rare root cause, typically used if the payment was submitted via draft (check). Bank endorsements provide guarantee that they will uphold the draft until it is going to be cashed out. If the draft is being processed and one of the banks in the processing chain does not provide endorsement, then the payment will return. |
RTN16 | Payment amount insufficient or minimum amount not met | |
RTN17 | Debits and credits not allowed | |
RTN18 | Other freeform reference included | Other freeform reference included – this reason should not reach the client on MP level. This is the reason that is chosen when the reason provided is unspecific and any of the other reasons can’t be applied. Typically, the client will see the code RTN18 but a specific reason provided instead of “Other freeform reference included”. This is a rare root cause, mostly used for banks that have very specific requirements for the payments to be processed, or if the payment processed had an isolated exception. |
RTN19 | No reason provided | This reason is used when we receive a return of funds without any explanation from the bank. Typically we aim to clarify the return reason by contacting the bank, however, not always will the bank be able to provide a reason (especially, if the payment was rejected by intermediary or beneficiary bank without reason). |
RTN20 | BBK internal policy | The payment was returned based on disclosed policies of the beneficiary bank. |
RTN21 | Beneficiary deceased | |
RTN22 | Beneficiary reference needed | |
RTN23 | Blocked account | |
RTN24 | Correspondent bank internal policy | The payment was returned based on disclosed policies of the correspondent bank. |
RTN25 | Duplicate payment | |
RTN26 | Foreign exchange relations | The payment did not meet the requirements for foreign exchange regulations. This may occur if exotic currencies are being transmitted without specific information, or if the banks in the transmission chain do not have the necessary requirements to process the currency further. |
RTN27 | IBK details missing or incorrect | Our correspondent bank can’t process the payment further, as the intermediary bank details are either invalid or not provided. This may happen when payment needs to travel through multiple banks until it reaches the beneficiary bank. |
RTN28 | IBK internal policy | The payment was returned based on disclosed policies of the correspondent bank. |
RTN29 | Only accepts SEPA payments | |
RTN30 | Overpayment | |
RTN31 | Per beneficiary request | |
RTN32 | Purpose of payment not provided or unclear | |
RTN33 | Refund | A rare root cause used in a situation where the bank is returning funds that have been refunded due to overpayment, or similar. |
RTN34 | Remitter details | Incomplete or invalid remitter details were provided. Typically before returning the funds we would receive a message stating from bank that they can not apply the funds due to incomplete/incorrect remitter details. Failing to provide them the information in time, or failing to retrieve the information from the client in time will result in payment being rejected and returned using this root cause. |
RTN35 | Stale dated draft | If a draft (check) payment was submitted, and it has not been cashed out for the duration of the draft’s age, the bank will return us the funds for the draft has turned stale. |
Updated 5 months ago