Error handling

The API client declares specific exception types under the arkindex.exceptions module that you can use to handle various errors.

Inheritance

SchemaError

An error occurred while retrieving or parsing the OpenAPI schema using the provided schema_url when instantiating the Arkindex client, or using the base_url followed by /api/v1/openapi/.

ClientError

Any error that prevents the client from making the request or fetching the response: invalid endpoint names or URLs, unsupported content types, or unknown request parameters. See the exception messages for more info.

ErrorResponse

The request resulted in a HTTP 4xx or 5xx response from the server.

This exception type contains additional attributes that you can use to get more details about the error:

title

A string containing the error code and its associated name.

status_code

The HTTP status code.

content

The body of the HTTP response. The client will attempt to parse this response using the Content-Type header returned by the server, but if this fails, the response will be left as an unparsed string.

from arkindex.exceptions import ErrorResponse
try:
    # cli.request ...
except ErrorResponse as e:
    print(e.title)   # "400 Bad Request"
    print(e.status_code)  # 400
    print(e.content)  # Any kind of response body the server might give

ArkindexError

A subclass of ErrorResponse raised when an error conforms to the standard Arkindex API error format. The content attribute of the exception is guaranteed to be a dict with the following keys:

type

Either "client_error", "server_error" or "validation_error".

errors

A list of dictionaries, one for each of the errors that occurred, with the following keys:

attr

List of strings or integers defining the path to a specific attribute on the HTTP headers, GET query parameters, or JSON parameters that this error relates to.

For example, "attr": ["items", 0, "name"] is equivalent to accessing ["items"][0]["name"] in Python.

When this error does not match any specific field, this attribute is set to either ["non_field_errors"] or None.

code

String representing a machine-readable error code.

detail

String representing a human-readable error message. This message is subject to change at any time and should not be parsed by scripts, only displayed.

Typical error content
{
    "type": "client_error",
    "errors": [
        {
            "attr": ["name"],
            "code": "required",
            "detail": "This field is required."
        }
    ]
}

ArkindexClientError

A subclass of ArkindexError that is raised only when the type of the error is client_error.

ArkindexServerError

A subclass of ArkindexError that is raised only when the type of the error is server_error.

ArkindexValidationError

A subclass of ArkindexError that is raised only when the type of the error is validation_error and the HTTP status code is 400.

ArkindexConflictError

A subclass of ArkindexClientError that is raised only when the HTTP status code is 409. The content attribute of the exception contains an additional key:

existing_id

Either the UUID of an existing object that conflicts with this item, or None.

Typical conflict error content
{
    "type": "client_error",
    "errors": [
        {
            "attr": None,
            "code": "conflict",
            "detail": "An item with this name already exists."
        }
    ],
    "existing_id": "d12f647d-a518-41eb-be55-c50b4f367688"
}

Only a small subset of API endpoints handle conflicts in this way. You can check if an endpoint supports this error by looking for the HTTP 409 response code in the API documentation.