Errors and transport

API failures raise a stable NosibleAPIError hierarchy. The base exception inherits from ValueError for compatibility with existing applications.

from nosible import Nosible, RateLimitError

try:
    Nosible().get_limits()
except RateLimitError as error:
    print(error.retry_after)

All API errors expose status_code, code, method, path, body, and retry_after.

Exception hierarchy

class NosibleAPIError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: ValueError

Base class for errors returned by a NOSIBLE HTTP endpoint.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class AuthenticationError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: NosibleAPIError

The request did not carry valid API credentials.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class ValidationError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: NosibleAPIError

The request failed local or remote validation.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class RateLimitError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: NosibleAPIError

A NOSIBLE rate limit was exhausted.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class ConflictError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: NosibleAPIError

The requested operation conflicts with current server state.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class GoneError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: NosibleAPIError

The requested resource is no longer available.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class CursorExpiredError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: GoneError

A pagination cursor refers to an index generation that has expired.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class AccessDeniedError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: NosibleAPIError

The credential is valid but cannot access the requested resource.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class NotFoundError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: NosibleAPIError

The requested resource was not found.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

class BackendError(message, status_code=None, code=None, method=None, path=None, body=None, retry_after=None)

Bases: NosibleAPIError

NOSIBLE or an upstream service could not complete the request.

Parameters:

  • message (str)

  • status_code (int | None)

  • code (str | None)

  • method (str | None)

  • path (str | None)

  • body (Any)

  • retry_after (float | None)

Retry behavior

Transport failures are retried up to the configured attempt count. HTTP 429, 500, 502, 503, and 504 responses are retried only for safe read requests, which avoids duplicating POST mutations or Search jobs. The client honors both numeric and HTTP-date Retry-After headers.

Presigned Bulk and Time download GETs follow the same retry policy for transient statuses. A 404 is returned to the polling layer rather than retried by the transport because it means the asynchronous result is not ready yet.

Pass base_url to target another merged API origin and http_client to inject an httpx.Client. The caller retains ownership of an injected client. Client-level authentication is disabled for presigned download requests.