Error Handling

HTTP Error Codes

In the Neonomics API, we use custom HTTP error codes.

  • 510 – Client Error: An error returned with a 510 code represents a client error. For example, if you have sent a post request with incorrect parameters, you will get an error with this HTTP code.
  • 520 – Neonomics Error: This represents an error in the Neonomics platform.
  • 530 – Bank Error: This represents an error from the bank.

Error object

Neonomics returns a JSON response object with the details of the error.

Error object:

{  
    "id": "3e67b166-47d5-4cea-82e9-37acaea551bc",  
    "errorCode": "1428",  
    "message": "This payment requires strong customer authorisation. Please use the authorisation URL provided to continue, then call the payment complete endpoint after authorising.",  
    "source": "C",  
    "type": "CONSENT",  
    "timestamp": 1554678903245,  
    "links": [  
      {  
        "type": "GET",  
        "rel": "payment",  
        "href": "https://dev-api.neonomics.io/ics/v3/payments/sepa-credit/519b1e62-e2dc-403a-973e-9ae1a902d686/authorize",  
        "meta":  
        {  
            "id": "519b1e62-e2dc-403a-973e-9ae1a902d686"  
        }  
      }  
    ]  
  }

Explanation of the attributes in an error message:

  • id – A unique ID of the error, used for debugging purposes. In connection with error reporting to Neonomics, it is called correlation ID.
  • errorCode – Custom error code that will help to categorize the error. When you are building business logic to identify and handle errors, it should be based on errorCode.
  • message – Description of the error. Note that the message text can change over time as new features are introduced, so you should never base your integration on this attribute.
  • source – Identifies the source of the error. For example, if it returns a "C", it is a client error.
  • type – The type of error. It is an enumerated type and can be one of the following errors: FATAL, NETWORK, BAD_REQUEST, AUTH and CONSENT.
  • timestamp – The timestamp of when an error was first detected. It is a UTC value (Coordinated Universal Time).
  • links – An object containing extra information.

Error codes

The error object has an errorCode attribute. There are three groups of error codes that can be returned:

Client error codes: 1000–2999

These are errors caused by the user. For these errors, Neonomics clients must check if the information inputted is correct and/or valid. View a complete list of error codes.

Neonomics error codes: 3000–3999

These are internal errors in the Neonomics platform. For these errors, Neonomics clients can retry the request in case of NETWORK error.

Bank error codes: 4000–5999

These are errors returned from the Bank. For these errors, Neonomics clients can retry the request in case of NETWORK error.

Error Types

Depending on the value of the error type, Neonomics clients can do the following actions:

  • FATAL – The client cannot retry the request.
  • NETWORK – The client can retry the same request.
  • BAD_REQUEST – The client can retry the request after making changes.
  • AUTH – Problem with authorization related to access to the Neonomics API. Trigger OAuth2.0 Client Credentials flow to get a token.
  • CONSENT – Problem with the consent towards the bank. Trigger a consent flow with the link information returned in the error object.