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
| Failure | Retried |
|---|---|
| Timeouts | Yes |
| Connection errors | Yes |
408, 409, 429, 500, 502, 503, 504 | Yes |
| Any other status | No. 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.
| Error | Raised when | Retried first |
|---|---|---|
BadRequestError | 400: the request is malformed. | No |
AuthenticationError | 401: the key is missing, malformed, or revoked. | No |
PermissionDeniedError | 403: the key isn't allowed this request. | No |
NotFoundError | 404: the engine, space, or route doesn't exist. | No |
UnprocessableEntityError | 422: the request didn't pass validation. | No |
RateLimitError | 429: a rate limit was hit. | Yes |
InternalServerError | 500 and above. | Yes, for 500, 502, 503, and 504 |
APIStatusError | Any other error status. Also the parent of every error above. | No |
APITimeoutError | The request timed out on every attempt. | Yes |
APIConnectionError | Docklee couldn't be reached on every attempt. Also the parent of APITimeoutError. | Yes |
Error fields
| Python | TypeScript | On | Description |
|---|---|---|---|
message | message | Every error | What went wrong. |
status_code | statusCode | APIStatusError and its subclasses | The HTTP status. |
response | response | APIStatusError and its subclasses | The error body from the API. |
retry_after | retryAfter | RateLimitError | Seconds 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:
| Message | Cause |
|---|---|
API key is required | No 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 integer | The dimension variable isn't a positive whole number. |
Dock instance is closed | capture 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.