04_error_handling.mdx

id	error-handling
title	Error handling
description	Handle API errors with the ApifyApiError exception and automatic data parsing.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import ApiLink from '@theme/ApiLink';

import ErrorAsyncExample from '!!raw-loader!./code/04_error_async.py'; import ErrorSyncExample from '!!raw-loader!./code/04_error_sync.py';

When you use the Apify client, it automatically extracts all relevant data from the endpoint and returns it in the expected format. Date strings, for instance, are seamlessly converted to Python datetime.datetime objects. If an error occurs, the client raises an ApifyApiError. This exception wraps the raw JSON errors returned by the API and provides additional context, making it easier to debug any issues that arise.

Error subclasses

The Apify client provides dedicated error subclasses based on the HTTP status code of the failed response, so you can branch on error kind without inspecting status_code or type:

Status	Subclass
400	InvalidRequestError
401	UnauthorizedError
403	ForbiddenError
404	NotFoundError
409	ConflictError
429	RateLimitError
5xx	ServerError

All subclasses inherit from ApifyApiError, so an existing except ApifyApiError handler still catches every API error. Catch a specific subclass when you want to react differently to, for example, a missing resource or a rate-limit:

{ErrorAsyncExample} {ErrorSyncExample}

For a complete list of error classes, see the ApifyApiError reference.