Errors and Warnings

API Validation Errors and Warnings

Data Validation Errors

The following are generic errors that may apply to API requests where invalid data types / values are provided in request parameters or the request body.

Scenario	Status Code	Notes
Complex Filtering (GET Contracts) Invalid data type supplied for field	400 Bad Request	The field name and provided value that caused the error are identified. Multiple errors may be included. Example: providing a value of "all" for a boolean input type and a value of "abc" for a numeric input type { "errors": [ { "message": "V200: Validation Errors", "extensions": [ { "code": "contractFilter", "messages": [ "The contractFilter field is required." ] }, { "code": "contractFilterSet[0].activeContracts", "messages": [ "Could not convert string to boolean: all. Path 'contractFilterSet[0].activeContracts', line 7, position 32." ] }, { "code": "contractFilterSet[0].userDefinedFieldFilters[0].userDefinedFieldId", "messages": [ "Could not convert string to integer: abc. Path 'contractFilterSet[0].userDefinedFieldFilters[0].userDefinedFieldId', line 11, position 37." ] } ] } ] }
Query String Filtering (eg; GET users, Get counterparties) Invalid data type supplied for parameter	400 Bad Request	{ "errors": [ { "message": "V200: Validation Errors", "extensions": [ { "code": "id", "messages": [ "The value 'john' is not valid." ] }, { "code": "pageSize", "messages": [ "The field must be null or greater than 0." ] } ] } ] }

Scenario

Status Code

Notes

Complex Filtering (GET Contracts)

Invalid data type supplied for field

400

Bad Request

The field name and provided value that caused the error are identified. Multiple errors may be included.

Example: providing a value of "all" for a boolean input type and a value of "abc" for a numeric input type

{
    "errors": [
        {
            "message": "V200: Validation Errors",
            "extensions": [
                {
                    "code": "contractFilter",
                    "messages": [
                        "The contractFilter field is required."
                    ]
                },
                {
                    "code": "contractFilterSet[0].activeContracts",
                    "messages": [
                        "Could not convert string to boolean: all. Path 'contractFilterSet[0].activeContracts', line 7, position 32."
                    ]
                },
                {
                    "code": "contractFilterSet[0].userDefinedFieldFilters[0].userDefinedFieldId",
                    "messages": [
                        "Could not convert string to integer: abc. Path 'contractFilterSet[0].userDefinedFieldFilters[0].userDefinedFieldId', line 11, position 37."
                    ]
                }
            ]
        }
    ]
}

Query String Filtering (eg; GET users, Get counterparties)

Invalid data type supplied for parameter

400

Bad Request

{
    "errors": [
        {
            "message": "V200: Validation Errors",
            "extensions": [
                {
                    "code": "id",
                    "messages": [
                        "The value 'john' is not valid."
                    ]
                },
                {
                    "code": "pageSize",
                    "messages": [
                        "The field must be null or greater than 0."
                    ]
                }
            ]
        }
    ]
}

Authorization Errors

The following are generic errors that may apply to any API requests.

Scenario	Status Code	Notes
IP Access Restriction	403 Forbidden	Attempted access from an IP Address outside of the restricted range / within denied access range. { "code": "AR001", "message": "Invalid address range for [source ip]" }
User is not authorized	403 Forbidden	The user context under which the API is logged in must have permission to the function within the specified business unit. An unauthorized message may also be shown if the business unit Id provided does not exist. { "errors": [ { "message": "A010: Authorization Errors", "extensions": [ { "key": "A010", "value": [ "No Business Unit was found matching Id 7 or you do not have permission" ] } ] } ] }

Scenario

Status Code

Notes

IP Access Restriction

403

Forbidden

Attempted access from an IP Address outside of the restricted range / within denied access range.

{
  "code": "AR001",
  "message": "Invalid address range for [source ip]"
}

User is not authorized

403

Forbidden

The user context under which the API is logged in must have permission to the function within the specified business unit.

An unauthorized message may also be shown if the business unit Id provided does not exist.

{
    "errors": [
        {
            "message": "A010: Authorization Errors",
            "extensions": [
                {
                    "key": "A010",
                    "value": [
                        "No Business Unit was found matching Id 7 or you do not have permission"
                    ]
                }
            ]
        }
    ]
}

Validation Errors / Warnings

Where a validation error or errors occur, the errors will be returned as a JSON object in the response.

The error will indicate the field or entity in the Key and the Value will provide detail on the cause of the error.

Where an update or create request supports the "Fail on Warnings" flag, and that flag is set to True, validation warnings trigger an error instead of a warning and will prevent the update/create from succeeding. Warnings that can be overriden by the "Fail on Warnings" flag are prefixed with "[Warning]" in the Value field.

If the request is resubmitted with the "Fail on Warnings" flag set to False, the warnings will still be returned, but will not fail the update and will be returned in the Warnings record instead.

Scenario	Status Code	Notes
Validation errors occurred	400 Bad Request	Where the create/update supports the failOnWarnings flag, when set to true, warnings that can be overridden will be shown as errors, with the [Warning] prefix to the message. { "errors": [ { "message": "V200: Validation Errors", "extensions": [ { "code": "Contract", "message": [ "[Warning]: One or more possible duplicates were found - Contract Id 2063: [Supplier Agreement with Acme Limited] [2024-05-10]" ] } ] } ] }
Validation warning occurred Create or Update	201 Created 200 OK	Attempting to process the same record as above with the failOnWarnings flag set to false results in a successful create, with the warning returned in the Warnings array. { "contractId": 2064, "warnings": [ { "code": "Contract", "message": "One or more possible duplicates were found - Contract Id 2063: [Supplier Agreement with Acme Limited] [2024-05-10]" } ] }

Scenario

Status Code

Notes

Validation errors occurred

400

Bad Request

Where the create/update supports the failOnWarnings flag, when set to true, warnings that can be overridden will be shown as errors, with the [Warning] prefix to the message.

{
    "errors": [
        {
            "message": "V200: Validation Errors",
            "extensions": [
                {
                    "code": "Contract",
                    "message": [
                        "[Warning]: One or more possible duplicates were found - Contract Id 2063: [Supplier Agreement with Acme Limited] [2024-05-10]"
                    ]
                }
            ]
        }
    ]
}

Validation warning occurred

Create or Update

201

Created

200

Attempting to process the same record as above with the failOnWarnings flag set to false results in a successful create, with the warning returned in the Warnings array.

{
    "contractId": 2064,
    "warnings": [
        {
            "code": "Contract",
            "message": "One or more possible duplicates were found - Contract Id 2063: [Supplier Agreement with Acme Limited] [2024-05-10]"
        }
    ]
}

API Library

When using the API Library, API calls should be within a try/catch block and should catch API exceptions with:

catch (ApiException<ContractEagleApi.ErrorDetails> ex)

Where the exception is caught, the HTTP Status Code will be available in the ex.StatusCode property. Errors generated by the processing are available in the ex.Result?.Errors? property, which returns a list of error records containing

Code
Message
Extensions

The Extensions contains the detailed list of Codes and a list of messages relating to the code. In validation errors, Code indicates the field name and the messages provide a detailed description of the error(s).