API errors

As described in the API introduction, the error object conforms to the Problem Details for HTTP APIs specification It is used to convey information about errors that occur while processing HTTP requests.

Below is a list of all potential API errors.

Unauthorized

The Authorization header is missing from the HTTP request, or has been sent with an invalid value.

Check the authorisation requirements of the endpoint, and send an appropriate token in the headers.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
3  "title": "Unauthorized",
4  "status": 401,
5  "error_code": "unauthorized",
6  "trace_id": "3643f86ed46106566fc9ffac4f811800"
7}

Forbidden

The provided token does not have permission to perform the requested operation.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
3  "title": "Forbidden",
4  "status": 403,
5  "error_code": "forbidden",
6  "trace_id": "d9f784ea4dad04d019ae38d86c237fb5"
7}

Invalid Request

Invalid request errors occur when there is an issue with the request body or headers. This can include validation errors where one or more fields are invalid, or cases where the request body contains malformed JSON or cannot be deserialized. The errors field is included in the response only if the error is related to specific fields.

Example: Validation Errors

One or more fields in the request body or headers were invalid.

The errors field included in the response will specify the JSON path of the request body fields or header names that were invalid, alongside at least one description of the error for each invalid field.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
3  "title": "Invalid request",
4  "status": 400,
5  "error_code": "invalid_request",
6  "errors": {
7    "legal_name": [
8      "The legal_name field is required"
9    ]
10  },
11  "trace_id": "ae3c4bd470e1d843e25d93201a501073"
12}

Example: Malformed JSON

The request body contains malformed JSON or cannot be deserialized (for example, a property value has the incorrect type).

In this case, the errors field is not included because the issue is with the overall request structure, not specific fields.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
3  "title": "Invalid request",
4  "status": 400,
5  "error_code": "invalid_request",
6  "detail": "Invalid parameter $.legal_name at line 1",
7  "trace_id": "91b9d777cf66a0c20a25ae59d24d4ce4"
8}

Invalid state

The requested operation is invalid given the current state of the resource.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
3  "title": "Invalid state",
4  "status": 400,
5  "error_code": "invalid_state",
6  "detail": "The employer offboarding cannot be cancelled, as it was not requested",
7  "trace_id": "ce817fda982145459fda00334f2b8e90"
8}

Not Found

The requested resource cannot be found. This can occur if an incorrect resource ID is used in the request.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
3  "title": "Resource not found",
4  "status": 404,
5  "error_code": "not_found",
6  "detail": "The requested employee could not be found",
7  "trace_id": "27a3c13bf162c8b34eabea432af17657"
8}

Idempotency Error

Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request’s API endpoint and parameters. This error ensures that duplicate requests with different parameters are not processed multiple times, maintaining the integrity and consistency of operations.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
3  "title": "Idempotency error",
4  "status": 409,
5  "error_code": "idempotency_error",
6  "detail": "The Idempotency-Key has already been used with a different request",
7  "trace_id": "12a4f7a2b5e84d98b7e6c7d9a1c4e8f9"
8}

Too Many Requests

Too many requests have been sent in a given amount of time, leading to rate limiting.

1{
2  "type": "https://tools.ietf.org/html/rfc6585#section-4",
3  "title": "Too many requests",
4  "error_code": "rate_limit_exceeded",
5  "status": 429,
6  "trace_id": "c5d9f46c1f8c4b3b9e9a2c3d4f8f6e2d",
7}

Third Party Error

This error indicates that there was an issue with a third-party service, which is necessary for the requested operation, such as an insurer API. Please try again later or contact support if the issue persists.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
3  "title": "Third party error",
4  "status": 500,
5  "error_code": "third_party_error",
6  "detail": "An error occurred while communicating with the insurance API",
7  "trace_id": "b3f0c6e2e2b14c6da8d7e8f1a2c7e0e1"
8}

Internal Error

An unexpected condition was encountered, and the server could not complete the request. Please try again later or contact support if the issue persists.

1{
2  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
3  "title": "An error occurred while processing your request",
4  "error_code": "internal_error",
5  "status": 500,
6  "trace_id": "69d92eb43c494c22c915bef11eb3989e"
7}
Was this page helpful?
Built with