Skip to Content

Reference

Errors and retries

Which failures the SDK retries for you, and which error it raises when a call can't succeed.

Networks drop requests and services get busy. The SDK retries the failures that are likely to pass on a second try, and raises a specific error for the ones that won't, so your code can handle each case.

What's retried

FailureRetried
TimeoutsYes
Connection errorsYes
408, 409, 429, 500, 502, 503, 504Yes
Any other statusNo. The matching error is raised at once.

The SDK waits 0.5 seconds before the first retry and doubles the wait each time, up to 8 seconds. It retries up to 3 times by default. Set max_retries (Python) or maxRetries (TypeScript) to change that, or 0 to turn retries off.

Errors

Every error extends DockleeError.

ErrorRaised whenRetried first
BadRequestError400: the request is malformed.No
AuthenticationError401: the key is missing, malformed, or revoked.No
PermissionDeniedError403: the key isn't allowed this request.No
NotFoundError404: the engine, space, or route doesn't exist.No
UnprocessableEntityError422: the request didn't pass validation.No
RateLimitError429: a rate limit was hit.Yes
InternalServerError500 and above.Yes, for 500, 502, 503, and 504
APIStatusErrorAny other error status. Also the parent of every error above.No
APITimeoutErrorThe request timed out on every attempt.Yes
APIConnectionErrorDocklee couldn't be reached on every attempt. Also the parent of APITimeoutError.Yes

Error fields

PythonTypeScriptOnDescription
messagemessageEvery errorWhat went wrong.
status_codestatusCodeAPIStatusError and its subclassesThe HTTP status.
responseresponseAPIStatusError and its subclassesThe error body from the API.
retry_afterretryAfterRateLimitErrorSeconds to wait, from the Retry-After header, when it's sent.

Handle errors

from docklee import (
    Lynk,
    APIConnectionError,
    AuthenticationError,
    PermissionDeniedError,
    RateLimitError,
)

lynk = Lynk()

try:
    records = lynk.recall_sync("display preferences", end_user="user_8f2c")
except AuthenticationError:
    raise SystemExit("Check DOCKLEE_API_KEY.")
except PermissionDeniedError as error:
    print("Key can't read this space:", error.message)
except RateLimitError as error:
    print("Rate limited. Retry after", error.retry_after, "seconds.")
except APIConnectionError:
    print("Docklee is unreachable. Try again shortly.")

Setup errors

Some problems are caught before any request is sent:

MessageCause
API key is requiredNo key was passed and DOCKLEE_API_KEY isn't set.
engine_id is required (Python), engineId is required (TypeScript)query or retrieve was called with no engine ID.
memory_space_id is required (Python), memorySpaceId is required (TypeScript)recall was called with no memory space ID.
DOCKLEE_DIMENSION must be a positive integerThe dimension variable isn't a positive whole number.
Dock instance is closedcapture was called after close.

In Python these are ValueError or RuntimeError. In TypeScript they're Error.

Writes that fail

Dock handles failed sends differently from reads. flush_sync() in Python and flush() in TypeScript don't raise. They keep the events in the buffer and return None or null, so a capture is never lost to a brief outage. See Batching and flush.

Next steps

Your code handles every failure. Start building with a full example.

On this page