Error responses

The Cardinus PACE API follows the standards specified in RFC7807 and RFC9457 relating to a standard format describing problems with the processing of a request sent to an API. All error responses will be in JSON format with the content-type set to application/problem+json. The properties are defined as:

Property	Description	Required (RFC 7807/9457)
type	A URI reference that identifies the problem type.	Yes
title	A short, human-readable summary of the problem type.	Yes
status	The HTTP status code generated by the server for this occurrence of the problem.	Yes
detail	A human-readable explanation specific to this occurrence of the problem.	No
instance	A URI reference that identifies the specific occurrence of the problem.	No

In addition to these properties, there may be additional properties such as traceId or errorId which can be used by technical support to help provide resolutions to problems. Ensure that the client parsing logic can ignore additional properties on the response object.

Below is an example response.

{
    "type": "https://docs.cardinus.com/articles/pace/api/http-codes.html#apidisabled",
    "title": "The API is disabled.",
    "status": 403,
    "detail": "The Cardinus PACE API is currently disabled.",
    "traceId": "00-17ff49018415637d79838e837677719e-53ab4d5cd690b435-00"
}

The type property will contain a link to the error in this article.

API access errors

ApiDisabled

Issue: The API is disabled.

Status: 403 Forbidden

Cause: The API has been disabled for the account. Contact Cardinus Support [email protected] who can advise.

EndpointNotFound

Issue: The URL does not resolve to an endpoint in the API.

Status: 404 Not Found

Cause: The URL used for accessing the PACE API doesn't resolve to an endpoint. Check the documentation for correct endpoint URLs.

InvalidApiKey

Issue: The supplied API key is not valid.

Status: 401 Unauthorized

Cause: The secure API key that was supplied in the header x-api-key was checked and found to not be valid. This could happen because it was submitted incorrectly, or the key has been revoked.

InvalidCustomerId

Issue: The Customer ID supplied is not valid.

Status: 401 Unauthorized

Cause: The customer ID is additional security for identifying the system which will be accessed. This error occurs when the value for the header x-api-id is not a valid customer ID. See Authentication for more information.

MethodNotAllowed

Issue: The endpoint doesn't support the HTTP method used.

Status: 405 Method Not Allowed

Cause: The resource exists at the given URL, but cannot process the HTTP method used. E.g. using the POST method when only GET is supported. The Allow header in the response will indicate the HTTP methods supported by that endpoint.

MissingApiKey

Issue: The API key is missing from the request.

Status: 401 Unauthorized

Cause: The secure API key must be included in every request using the header x-api-key. Ensure it is present in the request headers. See Authentication for more information.

MissingCustomerId

Issue: The Customer ID is missing from the request.

Status: 401 Unauthorized

Cause: The customer ID is additional security for identifying the system which will be accessed. This error occurs when the header x-api-id is missing from the request headers. See Authentication for more information.

QuotaExceeded

Issue: The client has reached the allowed quantity of requests.

Status: 429 Too Many Requests

Cause: Each customer gets a quota of requests that clients can make to the API. The error response will indicate when the quota resets. See Rate limits for more information. This quota depends upon the service subscription. Contact Cardinus Support [email protected] if you want to arrange a larger quota.

RateExceeded

Issue: The client has exceeded the allowed request rate.

Status: 429 Too Many Requests

Cause: This error indicates that the client or clients have sent too many requests in a short period of time. The response details will include details of the allowed rate and when more requests can be reattempted. See Rate limits for more information.

ScheduledMaintenance

Issue: The API is offline for scheduled maintenance.

Status: 503 Service Unavailable

Cause: The API has been restricted because the service is currently undergoing maintenance. Check back later when service has resumed.

Request issues

InvalidEntityDefinedFields

Issue: Supplied custom field values are the wrong type or fail validation.

Status: 400 Bad Request

Cause: The API cannot process the request because the values given are not the correct data type for the object being updated. Check the Entity Defined Field section in PACE to get the required data type and validation requirements.

InvalidOperation

Issue: The request made violates validation or business logic rules.

Status: 400 Bad Request

Cause: The request cannot be processed because the data supplied violates a requirement of the software. This could be due to a status of a record, or values falling outside a certain range. Check the details in the response for more information.

MalformedBody

Issue: The content in the request body cannot be processed as it is badly formed.

Status: 400 Bad Request

Cause: The content cannot be read because it is badly formed or not delivered completely. Check the body of the request is valid for the 'Content-Type' being submitted. E.g. if it is application/json then the content must be valid JSON. Where possible, the response from the PACE API will indicate what is wrong with the content.

MissingPayload

Issue: No payload was supplied with the request.

Status: 400 Bad Request

Cause: Some API endpoints require a payload with data. This error indicates that the payload has been left out of the request entirely. Check the documentation for the endpoint you are calling for details of the payload to include.

MissingProperties

Issue: Required properties are missing from the payload.

Status: 400 Bad Request

Cause: The API requires properties to complete processing the request which were not included in the request payload. The error response will indicate which properties it is expecting.

ProtectedRecord

Issue: Cannot update the given record.

Status: 403 Forbidden

Cause: The API will prevent changes to certain records. This error indicates that the record being updated is protected and the updates will be rejected.

RecordExists

Issue: Record with the given identifier already exists.

Status: 400 Bad Request

Cause: The request is to either create or update a record. The API ensures that unique identifiers are enforced, and the given payload is trying to set a duplicate unique identifier. The error response will indicate which field is supposed to be unique.

RecordNotFound

Issue: Record not found with given identifier.

Status: 404 Not Found

Cause: The given identifier has failed to resolve to any records. Ensure that the identifier given in the request is correct, and that the data has not been removed from the system.

ReportMissingParameters

Issue: Report requires additional parameters.

Status: 400 Bad Request

Cause: Some reports require parameters to be supplied in the request payload. The error response will indicate which parameters are missing from the request.

UnsupportedFormat

Issue: The format of the payload is not supported.

Status: 415 Unsupported Media Type

Cause: This error occurs when the format of the payload is incorrect. Ensure that the payload is in the JSON format and that the content-type header is specified as application/json.

General errors

FatalError

Issue: An unexpected error occurred which caused the request to fail.

Status: 500 Internal Server Error

Cause: This error is returned when an unexpected issue has caused the API to fail to process the request. If this error keeps happening then contact Cardinus Support [email protected] for help.

ReportError

Issue: Error while running report.

Status: 500 Internal Server Error

Cause: This error indicates that an error has happened while preparing the report. If this error continues contact Cardinus Support [email protected] for assistance.