Skip to main content

Error hierarchy

Identical class names in both languages (instanceof-discriminable in TS):
API errors expose the envelope’s errorCode and message. EnginiBuilderError is the exception: the workflow builder answers /v1/workflows* refusals in a different body (application/problem+json), so it carries code, status, path, fix, diagnostics and currentRevisionId (current_revision_id in Python) and is chosen by the body’s code, not the status - a builder 409 is not an EnginiConflictError. A 404 from the builder lookups (search_catalog / searchCatalog, list_tables / listTables and list_connections / listConnections on workflows) is one of these: it raises EnginiBuilderError with status 404 and a code, not EnginiNotFoundError, and has no requestId. Details and handling: Workflows. A 401 with no body (an authentication or gateway rejection) raises EnginiAuthError in both SDKs. Before engini 0.30.0 the Python SDK raised a plain EnginiAPIError for it; EnginiAuthError is a subclass of EnginiAPIError, so existing except EnginiAPIError handlers still catch it. EnginiToolExecutionError additionally carries error_message, execution_info, and history_id (errorMessage/executionInfo/historyId in TS).
The SDKs do not retry automatically. If your workload can hit rate limits or transient 5xx, wrap calls with your own retry/backoff and honor Retry-After on 429s.

Pagination

You don’t page manually: every list-style method auto-paginates internally and returns the complete array (tools.get, connections.list, connections.objects, applications.list, toolsets.list, executions.list). Use the REST API directly with offset/top if you need manual paging over very large sets - see the pagination contract.

Cursor paging

executions.list pages by cursor, not offset: executions are inserted continuously, and offset paging over a growing table repeats and skips rows. With no top it follows each page’s next_cursor (nextCursor in TypeScript) until the server omits it, 100 per page, and stops early on an empty page or a cursor the server repeats. Pass top to read one bounded page instead; executions.list_page / listPage returns the page with its next_cursor and total_count, and a cursor goes back in as cursor (not valid without top). Details and the sort limits: Executions. The TypeScript package also exports the helper, paginateCursor(fetchPage, { top }), an async generator over any cursor envelope: fetchPage(cursor, top) receives undefined for the first page, then each page’s nextCursor.