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.

Status CodeNameDescription
400Bad RequestReturned in the event of a bad request, due to malformed, incomplete, or incorrect data provided.
401UnauthorizedReturned when the platform cannot authorize the user.
404Not FoundReturned when a resource queried is not found in the current instance.
405Method Not AllowedThe method or endpoint utilized is not supported in the platform’s current release.
422Un-processable EntityReturned when the method was correct, but was rejected due to semantic issues.
429Too Many RequestsToo many requests have been received from the user within a predetermined time.

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.

Status CodeNameDescription
500Internal Server ErrorReturned when our platform is down, and the request is immediately rejected.
503Service UnavailableReturned when our platform can’t process the request, most likely due to maintenance issues or being overloaded from other requests.
504Gateway TimeoutReturned when our platform is having communication issues with its internal architecture and the request times out.

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
}

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 error related information is stored on the Transaction object and can be investigated by retrieving details about said payment.

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!