Skip to content

Error Handling

Error handling refers to the procedures by which a software application gracefully responds to and recovers from error conditions that may occur. All software applications should expect and seamlessly handle potential errors. While connectFi provides features necessary for efficient and eloquent error handling, such as client friendly 400 level error messages and deduplication capabilities, it is ultimately the client's responsibility to ensure that errors are handled and recovered from adroitly and effectively.

400 Level Errors

400, or 4xx, level errors occur when our server has received your request and error conditions have resulted in response to the received request. The error may arise from a response either in our system or from a back-office response. Most 400 level error responses follow this format:

    "requestId": "", //A unique ID specific to this request, generated by the server
    "code": "", //A short descriptive error code such as "referenceExists" or, if the error occurred in the back-office, "extBackOfficeName"
    "subCode": "", //The subCode may be present if one is returned by the back office
    "context": {
        //properties relevant to the error that has arisen
    "message": "" //A short description of why the error occurred

Additional information on 400 level errors can be found in the "Common Errors" section of the "Getting Started" documentation. Errors specific to individual services can be found in the API documentation of that service, under "Errors". The API Errors documentation contains a service level reference table documenting critical error codes, their labels, a description of why the error may occur, the context properties that will be returned with the error, and the http status level of the error. Actual examples of errors are also provided where available, including the error descriptions, the parameters and/or request body used to trigger the error, and the error response body that was returned.

500 Level Errors

500, or 5xx, level errors occur when server side error conditions arise.

For example, temporary outages may occur in our service, your service, or the network in between. Such outages are rare, but should be expected and handled accordingly. If this happens, the server would respond with a 503 "Service Unavailable" error.

One possible cause of a 503 level error would be a sudden spike in request volume. Our API is configured to optimize both service and costs - thus resources are allocated accordingly. Each assigned container can handle a certain transactions per second (tps) rate limit. If the tps rate limit is exceeded, the server may respond temporarily with a 503 level error. Our system will then automatically scale up and assign additional containers to handle the increase in load. This adjustment process takes approximately 30 seconds and, once complete, will allow the system to handle an increased tps rate. Once the request volume returns to an expected tps rate for an extended time period, the system will automatically scale back down to the standard number of containers.

There are multiple strategies that you can choose to implement in order to handle this type of situation. One way to avoid exceeding your tps rate limit would be to send requests as your customers make them throughout the day (individually or in small batches that do not exceed your tps rate limit). If possible, avoid large, sudden spikes in request volume. If you do receive a 503 error, we recommend that you wait approximately 30 seconds for the system to scale up and then use the GET /health endpoint to ensure that the service is once again available before continuing to send requests.

Deduplication and Idempotency

If a 5xx level error does occur, it is possible that you may have a request in your system that is in an unknown status in our system. Before making the decision on whether or not you should resend the request, we recommend that you first check to make sure you will not be sending duplicate or redundant requests. Any request that will create a new entity in our system (such as a transaction) requires a unique, external reference ID that will:

  • Allow you to query the current status of the request, if it exists in our system.
  • Enable you to ensure deduplication of your requests.

Let's take a look at an example of what might happen if a 503 error occurs when initiating a new transaction using the /transfer-to/bills/initiate endpoint.

Imagine that the following request is sent and a 503 "Service Unavailable" error is received in response.

    "amount": 1.01,
    "currency": "USD",
    "reference": "extTrnBill400",
    "billerId": "0003000666",
    "accountNumber": "123456789",
    "firstName": "Joe",
    "lastName": "Doe",
    "deliveryTimeCode" : "N",
    "webhookUrl": "https://your_webhook_url/extTrnBill400",
    "narrative": "Your message here"

The reference ID, "extTrnBill400", is an external reference that is generated by you (the client) and sent as a required property in the request body. This endpoint supports idempotency - the reference ID must be unique in our system and is how connectFi controls for duplicate transactions. If the same reference ID is used in two different requests, you will receive a "referenceExists" error and there will not be a new transaction initiated.

Likewise, if you send two requests with different reference IDs, even if every other property is exactly the same, then you will initiate two separate transactions. Thus, if you receive a 503 error, you should not just resend the request with a new reference ID, as this could potentially create duplicate requests. Instead, first make a /transfer-to/bills/query request using the original transaction reference ID. If the transaction exists in our system, the query will return the transaction details with the current transaction status. If the transaction does not exist in our system, then the 503 error occurred before the transaction entity was created in connectFi. In this case, the transaction was not initiated and will not be processed. After verifying whether the transaction exists in our system and what the current status is (if it does exist), then you can make the decision whether or not to resend the request.