djblets.webapi.errors¶

Error classes and codes for WebAPI.

class WebAPIError(code: int, msg: str, *, http_status: int = 400, headers: _HTTPHeadersOrCallable = {}, error_type: Optional[str] = None, error_subtype: Optional[str] = None, detail: Optional[str] = None, trace_id: Optional[str] = None)[source]¶

Bases: object

An API error, containing an error code and human readable message.

Changed in version 4.0:

Added Python type hints.
Added detail, error_type, and error_subtype, and trace_id attributes.

__init__(code: int, msg: str, *, http_status: int = 400, headers: _HTTPHeadersOrCallable = {}, error_type: Optional[str] = None, error_subtype: Optional[str] = None, detail: Optional[str] = None, trace_id: Optional[str] = None) → None[source]¶

Initialize the error.

Changed in version 4.0:

Added error_type, error_subtype, detail, and trace_id attributes.
http_status and headers must be provided as a keyword. Passing as positional arguments is deprecated and will be removed in Djblets 6.

Parameters:

code (int) – The numeric code for the error.
msg (str) – The error message shown to the caller.
http_status (int, optional) –
The HTTP status code for the error.

This defaults to HTTP 400 Bad Request.
headers (dict or callable, optional) –
Extra HTTP headers to include in the error’s HTTP response.

This may also be a callable that returns HTTP headers, given an HTTP request.
error_type (str, optional) –
A string indicating the type of the error.

This is a string equivalent to code, and is used to allow callers to differentiate between errors. It may be accompanied by error_subtype.

Third-party errors (such as those provided by extensions) should be in the form of x-vendor-type.

New in version 4.0.
error_subtype (str, optional) –
A string indicating the subtype of the error.

This can provide additional context beyond code or error_type.

Third-party errors (such as those provided by extensions) should be in the form of x-vendor-type.

New in version 4.0.
detail (str, optional) –
An message used to convey additional details on this error.

New in version 4.0.
trace_id (str, optional) –
An ID shown in the error that’s associated with logs.

This can be supplied using with_overrides() in order to associate the error with logged output containing more detail.

New in version 4.0.

code: int¶

The numeric code for the error.

This may be used along with error_type, depending on the consumer’s API requirements. This was the original error type indicator prior to Djblets 4.

Type:: int

msg: str¶

The error message shown to the caller.

Type:: str

http_status: int¶

The HTTP status code of the error.

Type:: int

headers: _HTTPHeadersOrCallable¶

Extra HTTP headers included in the error’s HTTP response.

This may also be a callable that returns HTTP headers, given an HTTP request.

Type:: dict or callable

error_type: Optional[str]¶

A string indicating the type of the error.

This is a string equivalent to code, and is used to allow callers to differentiate between errors. It may be accompanied by a error_subtype`.

New in version 4.0.

error_subtype: Optional[str]¶

A string indicating the subtype of the error.

This can provide additional context beyond code or error_type.

New in version 4.0.

detail: Optional[str]¶: A message used to convey additional detail on this error.

New in version 4.0.

trace_id: Optional[str]¶

An ID shown in the error that’s associated with logs.

This can be supplied using with_overrides() in order to associate the error with logged output containing more detail.

New in version 4.0.

__repr__() → str[source]¶

Return a string representation of the error.

Returns:: The string representation.
Return type:: str

with_overrides(msg: Optional[str] = None, *, headers: Optional[_HTTPHeadersOrCallable] = None, error_subtype: Optional[str] = None, detail: Optional[str] = None, trace_id: Optional[str] = None) → Self[source]¶

Return an error with overridden values.

The returned error will be based on this error, but with a custom message or headers.

Changed in version 4.0:

Added error_subtype, detail, and trace_id attributes.
headers must be provided as a keyword. Passing as a positional argument is deprecated and will be removed in Djblets 6.

Parameters:

msg (str, optional) – The custom error message.
headers (dict or callable, optional) –
Custom HTTP headers to include in the error’s HTTP response.

This may also be a callable that returns HTTP headers, given an HTTP request.

These will override the default HTTP headers for the error.
error_subtype (str, optional) –
A string indicating the subtype of the error.

This can provide additional context beyond code or error_type.

Third-party errors (such as those provided by extensions) should be in the form of x-vendor-type.

New in version 4.0.
detail (str, optional) –
An message used to convey additional details on this error.

New in version 4.0.
trace_id (str, optional) –
An ID shown in the error that’s associated with logs.

This can be supplied using with_overrides() in order to associate the error with logged output containing more detail.

New in version 4.0.

Returns:

The new error instance.

Return type:

WebAPIError

with_message(msg: str) → Self[source]¶

Return an error with an overridden error message.

The returned error will be based on this error, but with a custom message.

Parameters:: msg (str) – The custom error message.
Returns:: The new error instance.
Return type:: WebAPIError

__annotations__ = {'code': 'int', 'detail': 'Optional[str]', 'error_subtype': 'Optional[str]', 'error_type': 'Optional[str]', 'headers': '_HTTPHeadersOrCallable', 'http_status': 'int', 'msg': 'str', 'trace_id': 'Optional[str]'}¶

exception WebAPITokenGenerationError[source]¶

Bases: Exception

An error generating a Web API token.

NO_ERROR = <API Error 0, HTTP 400: If you see this, yell at the developers>[source]¶

An error indicating no error occurred.

This should never be encountered.

SERVICE_NOT_CONFIGURED = <API Error 1, HTTP 503: The web service has not yet been configured>[source]¶: An error indicating the web service is not configured.

DOES_NOT_EXIST = <API Error 100, HTTP 404: Object does not exist>[source]¶: An error indicating a requested resource does not exist.

PERMISSION_DENIED = <API Error 101, HTTP 403: You don't have permission for this>[source]¶

An error indicating the user doesn’t have permission for a resource.

The user may not have read access or write access to the resource.

INVALID_ATTRIBUTE = <API Error 102, HTTP 400: Invalid attribute>[source]¶

An error indicating a resource doesn’t support an attribute for the request.

This should be used when performing a request to a resource that’s dependent on some attribute (such as a capability flag, setting, or associated resource) on the requested resource being available or set to an expected value, or when the request is missing the attribute.

This response payload should contain a top-level reason field with an error message.

For invalid request fields, see INVALID_FORM_DATA.

NOT_LOGGED_IN = <API Error 103, HTTP 401: You are not logged in>[source]¶

An error indicating that the user is not logged in.

This can be used to require authenticating to the API before making the request.

LOGIN_FAILED = <API Error 104, HTTP 401: The username or password was not correct>[source]¶: An error indicating that authentication failed.

INVALID_FORM_DATA = <API Error 105, HTTP 400: One or more fields had errors>[source]¶

An error indicating data submitted in the request is invalid.

Callers should set fields at the top of the payload to a dictionary mapping field names to lists of error mesages.

MISSING_ATTRIBUTE = <API Error 106, HTTP 400: Missing value for the attribute>[source]¶

An error indicating a required attribute in a request is missing.

This is usually a missing attribute in the request data provided for a resource.

ENABLE_EXTENSION_FAILED = <API Error 107, HTTP 500: There was a problem enabling the extension>[source]¶: An error indicating an extension couldn’t be enabled.

DISABLE_EXTENSION_FAILED = <API Error 108, HTTP 500: There was a problem disabling the extension>[source]¶: An error indicating an extension couldn’t be disabled.

EXTENSION_INSTALLED = <API Error 109, HTTP 409: This extension has already been installed.>[source]¶

An error indicating an extension is already installed.

This is used when trying to install an extension that is already installed.

INSTALL_EXTENSION_FAILED = <API Error 110, HTTP 409: An error occurred while installing the extension>[source]¶: An error indicating an extension installation failed.

DUPLICATE_ITEM = <API Error 111, HTTP 409: An entry for this item or its unique key(s) already exists>[source]¶

An error indicating an item conflicts with another.

This is used when attempting to perform a request that would result in a conflict between resources on the server.

OAUTH_MISSING_SCOPE_ERROR = <API Error 112, HTTP 403: Your OAuth2 token lacks the necessary scopes for this request.>[source]¶: An error indicating an OAuth2 token lacks a required scope.

OAUTH_ACCESS_DENIED_ERROR = <API Error 113, HTTP 403: OAuth2 token access for this resource is prohibited.>[source]¶: An error indicating an OAuth2 token cannot be used to access the resource.

RATE_LIMIT_EXCEEDED = <API Error 114, HTTP 429: API rate limit has been exceeded.>[source]¶: An error indicating the API rate limit has been exceeded.