Error Detail and Resolution

Errors happen, and when they do, Newline provides information that allows Clients to self-resolve and re-attempt. Our platform contains a hierarchy of error responses and failure reasons, so this guide can be your introduction into error handling with Newline.

While we've written these guides to cover the key feature interactions, we know that questions will still pop-up, as with any implementation (first-time or veteran). Our Sales and Partnership team is waiting and ready to start fielding questions on our API experience.

Resolving API Errors

If you are having issues with creating successful requests to either our Sandbox or Production APIs, please first review our API reference docs. These docs detail everything needed to create a successful request; in addition, we've included both success and error responses, calling out some common mistakes we've observed.

Understanding HTTP Status Codes

User-source Errors (4xx responses)

Also known as client errors, 4xx HTTP responses indicate that something errant was provided in the initial API call, be it in the path and query parameter or in the request body. The following table describes the 4xx responses supported by Newline.

In most scenarios with 4xx error responses, we advise referring to the appropriate API reference docs as well as our overview guide detailing the platform’s constraints.

System-source Errors (5xx responses)

Also known as server errors, 5xx HTTP responses indicate that something errant occurred during our platform’s execution phase. The following table describes the 5xx responses supported by Newline.

Platform Error Codes

In addition to the typical 4xx and 5xx error codes, Newline supports a number of platform specific codes that provide additional detail for the user, and are broken out by resource object. See the API Errors guide for more detail.

Below is an example error response:

{
  "errors": [
    {
       //Code provided by the Newline Platform for reference
      "code": 4111,
      //Title of Error Code
      "title": "Incomplete Customer details",
      //Description of Error Code
      "detail": "Customer is missing required information", 
      //Error Timestamp
      "occurred_at": "2022-10-21T18:22:22.300Z", 
      //Additional context to help users self-solve the error
      "extra": "First name can't be blank; Last name can't be blank; City can't be blank; Dob can't be blank; Phone can't be blank; Postal code can't be blank; Ssn can't be blank; State can't be blank; Street1 can't be blank"
    }
  ],
  "status": 422
}

Payment Network Errors

Lastly, errors can be thrown by the respective network (dependent on payment rail) after Newline has executed the payment. For instance, if a counterparty's account is no longer open at the receiving financial institution, Newline will receive this information and move the Transaction to the failed status.

It's worth noting that Network Errors are not returned via an error response like the above categories, rather related information is stored on the Transaction object (see the failure_code and failure_reason fields) and can be investigated by retrieving details about said payment.

To retry or not to retry, that is the question!

Having multiple layers of error responses can make it difficult to quickly understand whether to re-attempt an API request. To help simplify this decision process, we've provided a quick guide on how to triage.

Step 1: Review and identify the HTTP Status code

4xx codes indicate that their was an issue with the submitted API request, so if received, Clients should investigate the specific error details (see next steps); however, if a 5xx code is received, retrying would not be suggested as Newline is experiencing a system-level issue and can't process the request.

5xx codes are often referred to as system errors meaning that Newline had issues receiving the request, and could not interpret the request's intent.

In this scenario, please reach out to your Newline Specialist so we can review and identify the issue's root cause.

Step 2: Review the Platform code, detail, and extra fields

Platform code, detail, and extra fields (see above example response) provide key information about the issue that's occurred, what object (i.e. a Synthetic Account, a Transfer, etc.) is in question, and can also provide context on how Clients can self-solve.

Newline can also experience system errors after successfully receiving a request; this often times occurs when Newline has an issue processing the request. Clients can identify these errors using the detail field, as they start with a common phrase, "An exception occurred...".

In this scenario, similarly reach out to your Newline Specialist.

Step 3: If reviewing failed Transactions, identify the failure reason

Reviewing Transfer or Transaction issues requires Clients to confirm what caused their Transfer to result in a failed status. Clients should pull the Transaction in question and review the attached failure_code and failure_reason fields.

Transfers will typically fail when an error is caught by the payment network or by the receiving financial institution. Any detail sourced from these downstream partners is then included on the failure_code and failure_reason fields.

For example, if an ACH entry fails (in other words, is returned) and the failure_code is R08, this means that the counterparty made a request to their financial institution that the submitted debit be stopped.

Newline would advise Clients to not immediately retry failed transactions as it often requires data updates and successive failed transactions (after being initially alerted) can result in payment network penalties and fines.

Submitting invalid or incorrect information

In some instances, incorrect or invalid information may be provided on a Transfer request. If caught quickly, Clients can utilize the cancel a Transfer endpoint.

If the transaction has moved into an execution stage, please reach out to your Relationship team or your Newline Specialist for your resolution options. These options are often dependent on Payment Rail, so please refer to our ACH, Wire, and Instant Payments guides for additional information.

Support Teams Available

If you still have any questions or can't seem to resolve a persistent issue, please don't hesitate to reach out to our Sales & Partnership team or your Newline Specialist!