API - errors

Introduction

Any call to the API may result with an error response. Errors are identified by HTTP response status code and optional message in HTTP response body.

Errors

499 - Business validation error

Some business requirement is not met.
Details are in JSON format in HTTP response body.

423 - Some business object is currently in use. Try again later

Some resource (eg. business object) required to process given request is currently locked by another process in the system.
Eg. given contract is being recalculated thus cannot start another recalculation process now

You should wait some time and try again to execute desired API request.

400 - Bad request

That response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error. For example, it can invalid request message framing.

401 - Unauthorized

That response status code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.

403 - Forbidden

That response status code indicates that the server understands the request but refuses to authorize it.

404 - Not found

That response status code indicates that the server cannot find the requested resource. That response also indicates that the resource is missing. 

405 - Method not allowed

That response status code indicates that the server knows the request method but the target resource doesn`t support this method.

408 - Request Timeout

That response status code indicates that the server would like to shut down this unused connection. It is sent on an idle connection by some servers, even without any previous request by the client.

499 - Business validation error

When API return 499 HTTP code then the response contains JSON formatted message describing details of the error.

This a list of validation errors containing human readable message, error code and optionally name of request property if its value caused the error.

You should use code values to create logic handling API errors.

Example of 499 error response:

{
    "errors": [
        {
            "message": "Value must be number greater than 0",
            "property": "PaymentPlanId",
            "code": "ValueMustBeGreaterThan0",
            "nestedBusinessErrors": [],
            "data": null
        },
        {
            "message": "The StartDate field is required.",
            "property": "StartDate",
            "code": "MissingRequiredField",
            "nestedBusinessErrors": [],
            "data": null
        }
    ]
}

Error codes

Possible error codes are listed in API reference (click "Example value" in 499 code description) for each endpoint.

There are also generic error codes which may be returned from all API endpoints:

• MissingRequiredField

  Required field value is missing.

• ValueMustBeGreaterThan0

  Field value must be a number greater than 0.

• InvalidUri

  Field value must be a valid URL