Skip to content

docs: document public API errors #92

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cjumel merged 1 commit into from
Sep 15, 2026
Merged

docs: document public API errors #92

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions src/linkup/_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -268,9 +268,12 @@ def search(
LinkupInvalidRequestError: If the request parameters are invalid, including an invalid
or missing structured_output_schema when output_type is "structured".
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupPaymentRequiredError: If the endpoint requires x402 payment.
LinkupInsufficientCreditError: If you have run out of credit.
LinkupBudgetLimitExceededError: If the API key has reached its configured budget limit.
LinkupNoResultError: If the search query did not yield any result.
LinkupTooManyRequestsError: If the API rate limit is exceeded.
LinkupTimeoutError: If the request times out.
"""
params: dict[str, str | bool | int | list[str]] = self._get_search_params(
Expand Down Expand Up @@ -467,9 +470,12 @@ async def async_search(
LinkupInvalidRequestError: If the request parameters are invalid, including an invalid
or missing structured_output_schema when output_type is "structured".
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupPaymentRequiredError: If the endpoint requires x402 payment.
LinkupInsufficientCreditError: If you have run out of credit.
LinkupBudgetLimitExceededError: If the API key has reached its configured budget limit.
LinkupNoResultError: If the search query did not yield any result.
LinkupTooManyRequestsError: If the API rate limit is exceeded.
LinkupTimeoutError: If the request times out.
"""
params: dict[str, str | bool | int | list[str]] = self._get_search_params(
Expand Down Expand Up @@ -547,8 +553,12 @@ def research(
pydantic.BaseModel when provided.
LinkupInvalidRequestError: If the request parameters are invalid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupPaymentRequiredError: If the endpoint requires x402 payment.
LinkupInsufficientCreditError: If you have run out of credit.
LinkupBudgetLimitExceededError: If the API key has reached its configured budget limit.
LinkupTasksQueueLimitExceededError: If too many tasks are already pending or processing.
LinkupTooManyRequestsError: If the API rate limit is exceeded.
LinkupTimeoutError: If the request times out.
"""
params = self._get_research_params(
Expand Down Expand Up @@ -619,8 +629,12 @@ async def async_research(
pydantic.BaseModel when provided.
LinkupInvalidRequestError: If the request parameters are invalid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupPaymentRequiredError: If the endpoint requires x402 payment.
LinkupInsufficientCreditError: If you have run out of credit.
LinkupBudgetLimitExceededError: If the API key has reached its configured budget limit.
LinkupTasksQueueLimitExceededError: If too many tasks are already pending or processing.
LinkupTooManyRequestsError: If the API rate limit is exceeded.
LinkupTimeoutError: If the request times out.
"""
params = self._get_research_params(
Expand Down Expand Up @@ -670,6 +684,7 @@ def list_research(
Raises:
LinkupInvalidRequestError: If the pagination or sorting parameters are invalid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupTimeoutError: If the request times out.
"""
response = self._request(
Expand Down Expand Up @@ -712,6 +727,7 @@ async def async_list_research(
Raises:
LinkupInvalidRequestError: If the pagination or sorting parameters are invalid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupTimeoutError: If the request times out.
"""
response = await self._async_request(
Expand Down Expand Up @@ -740,8 +756,10 @@ def get_research(self, research_id: str, timeout: float | None = None) -> Linkup
The requested research task.

Raises:
LinkupInvalidRequestError: If the research identifier is not a valid UUID.
LinkupTaskNotFoundError: If the research identifier does not match an existing task.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupTimeoutError: If the request times out.
"""
response = self._request(
Expand All @@ -766,8 +784,10 @@ async def async_get_research(
The requested research task.

Raises:
LinkupInvalidRequestError: If the research identifier is not a valid UUID.
LinkupTaskNotFoundError: If the research identifier does not match an existing task.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupTimeoutError: If the request times out.
"""
response = await self._async_request(
Expand Down Expand Up @@ -797,8 +817,11 @@ def create_tasks(
an unsupported type.
LinkupInvalidRequestError: If the task payload is invalid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupInsufficientCreditError: If you have run out of credit.
LinkupBudgetLimitExceededError: If the API key has reached its configured budget limit.
LinkupTasksQueueLimitExceededError: If too many tasks are already pending or processing.
LinkupTooManyRequestsError: If the API rate limit is exceeded.
LinkupTimeoutError: If the request times out.
"""
response = self._request(
Expand Down Expand Up @@ -830,8 +853,11 @@ async def async_create_tasks(
an unsupported type.
LinkupInvalidRequestError: If the task payload is invalid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupInsufficientCreditError: If you have run out of credit.
LinkupBudgetLimitExceededError: If the API key has reached its configured budget limit.
LinkupTasksQueueLimitExceededError: If too many tasks are already pending or processing.
LinkupTooManyRequestsError: If the API rate limit is exceeded.
LinkupTimeoutError: If the request times out.
"""
response = await self._async_request(
Expand Down Expand Up @@ -879,6 +905,7 @@ def list_tasks(
LinkupInvalidRequestError: If the filtering, pagination, or sorting parameters are
invalid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupTimeoutError: If the request times out.
"""
response = self._request(
Expand Down Expand Up @@ -932,6 +959,7 @@ async def async_list_tasks(
LinkupInvalidRequestError: If the filtering, pagination, or sorting parameters are
invalid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupTimeoutError: If the request times out.
"""
response = await self._async_request(
Expand Down Expand Up @@ -962,8 +990,10 @@ def get_task(self, task_id: str, timeout: float | None = None) -> LinkupTask:
The requested task, parsed according to its task type.

Raises:
LinkupInvalidRequestError: If the task identifier is not a valid UUID.
LinkupTaskNotFoundError: If the task identifier does not match an existing task.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupTimeoutError: If the request times out.
"""
response = self._request(
Expand All @@ -986,8 +1016,10 @@ async def async_get_task(self, task_id: str, timeout: float | None = None) -> Li
The requested task, parsed according to its task type.

Raises:
LinkupInvalidRequestError: If the task identifier is not a valid UUID.
LinkupTaskNotFoundError: If the task identifier does not match an existing task.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupTimeoutError: If the request times out.
"""
response = await self._async_request(
Expand Down Expand Up @@ -1039,12 +1071,18 @@ def fetch(

Raises:
LinkupInvalidRequestError: If the provided URL is not valid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupPaymentRequiredError: If the endpoint requires x402 payment.
LinkupInsufficientCreditError: If you have run out of credit.
LinkupBudgetLimitExceededError: If the API key has reached its configured budget limit.
LinkupFailedFetchError: If the provided URL can't be fetched.
LinkupFetchResponseTooLargeError: If the fetch response is too large.
LinkupFetchTargetNotFoundError: If the target URL is not found.
LinkupFetchTargetUnreachableError: If the target URL cannot be reached.
LinkupFetchUnsupportedContentTypeError: If the URL resolves to an unsupported content
type.
LinkupTooManyRequestsError: If the API rate limit is exceeded.
LinkupTimeoutError: If the request times out.
"""
params: dict[str, Any] = self._get_fetch_params(
Expand Down Expand Up @@ -1108,12 +1146,18 @@ async def async_fetch(

Raises:
LinkupInvalidRequestError: If the provided URL is not valid.
LinkupAuthenticationError: If the Linkup API key is invalid.
LinkupIpNotWhitelistedError: If the request IP is not allowed by the API key.
LinkupPaymentRequiredError: If the endpoint requires x402 payment.
LinkupInsufficientCreditError: If you have run out of credit.
LinkupBudgetLimitExceededError: If the API key has reached its configured budget limit.
LinkupFailedFetchError: If the provided URL can't be fetched.
LinkupFetchResponseTooLargeError: If the fetch response is too large.
LinkupFetchTargetNotFoundError: If the target URL is not found.
LinkupFetchTargetUnreachableError: If the target URL cannot be reached.
LinkupFetchUnsupportedContentTypeError: If the URL resolves to an unsupported content
type.
LinkupTooManyRequestsError: If the API rate limit is exceeded.
LinkupTimeoutError: If the request times out.
"""
params: dict[str, Any] = self._get_fetch_params(
Expand Down
Loading