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)¶
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
, anderror_subtype
, andtrace_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 ¶
Initialize the error.
Changed in version 4.0:
Added
error_type
,error_subtype
,detail
, andtrace_id
attributes.http_status
andheaders
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
orcallable
, 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 byerror_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
orerror_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:
- 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
orcallable
- 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 aerror_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
orerror_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 ¶
Return a string representation of the error.
- Returns:
The string representation.
- Return type:
- 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 ¶
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
, andtrace_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
orcallable
, 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
orerror_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:
- with_message(msg: str) Self ¶
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:
- __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]'}¶
- NO_ERROR = <API Error 0, HTTP 400: If you see this, yell at the developers>¶
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>¶
An error indicating the web service is not configured.
- DOES_NOT_EXIST = <API Error 100, HTTP 404: Object does not exist>¶
An error indicating a requested resource does not exist.
- PERMISSION_DENIED = <API Error 101, HTTP 403: You don't have permission for this>¶
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>¶
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>¶
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>¶
An error indicating that authentication failed.
- INVALID_FORM_DATA = <API Error 105, HTTP 400: One or more fields had errors>¶
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>¶
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>¶
An error indicating an extension couldn’t be enabled.
- DISABLE_EXTENSION_FAILED = <API Error 108, HTTP 500: There was a problem disabling the extension>¶
An error indicating an extension couldn’t be disabled.
- EXTENSION_INSTALLED = <API Error 109, HTTP 409: This extension has already been installed.>¶
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>¶
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>¶
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.>¶
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.>¶
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.>¶
An error indicating the API rate limit has been exceeded.