Exceptions

Exception Hierarchy

All SDK exceptions inherit from NoukaiError:

NoukaiError (base)
├── APIConnectionError
├── APITimeoutError
├── AuthenticationError
├── PermissionDeniedError
├── FlowNotFoundError
├── InsufficientCreditsError
├── RateLimitError
├── FlowExecutionError
└── ToolCallLimitError

`NoukaiError`

Base class for all Noukai SDK exceptions.

Attributes:

code (str): Error code for programmatic dispatch
message (str): Human-readable error message
status_code (int, optional): HTTP status code (if applicable)

Example:

try:
    result = await flow.execute(message="hello")
except NoukaiError as e:
    print(f"Code: {e.code}")
    print(f"Message: {e.message}")

`AuthenticationError`

API key is invalid, missing, or expired.

Code: authentication_error
HTTP Status: 401

Causes:

No API key provided
Invalid API key prefix (not starting with nk_)
API key is revoked or expired

Example:

try:
    client = Noukai(api_key="invalid_key")
except AuthenticationError:
    print("Check your API key at https://console.noukai.xyz")

`PermissionDeniedError`

User lacks permission to access the flow.

Code: permission_denied
HTTP Status: 403

Causes:

Flow is private and user doesn't have access
User role doesn't allow flow execution

Example:

try:
    result = await flow.execute(message="hello")
except PermissionDeniedError:
    print("You don't have access to this flow")

`FlowNotFoundError`

Flow doesn't exist or was deleted.

Code: flow_not_found
HTTP Status: 404

Causes:

Flow slug is incorrect
Flow was deleted
Flow is in a different organization/project

Example:

try:
    result = await flow.execute(message="hello")
except FlowNotFoundError:
    print("Check flow slug at https://console.noukai.xyz/flows")

`InsufficientCreditsError`

Account has no remaining credits.

Code: insufficient_credits
HTTP Status: 402

Causes:

Account balance is zero
Credits expired

Example:

try:
    result = await flow.execute(message="hello")
except InsufficientCreditsError:
    print("Add credits at https://console.noukai.xyz/billing")

`RateLimitError`

Request rate limit exceeded.

Code: rate_limit_exceeded
HTTP Status: 429

Causes:

Too many requests in a short time
Concurrent request limit exceeded

Example:

import time
 
try:
    result = await flow.execute(message="hello")
except RateLimitError:
    print("Rate limited. Backing off...")
    time.sleep(60)
    # Retry

`APITimeoutError`

Request timed out.

Code: api_timeout
HTTP Status: 504

Causes:

Network latency
Noukai service slow
Request timeout exceeded

Note: The SDK automatically retries once on timeout. This exception means both attempts failed.

Example:

try:
    result = await flow.execute(message="hello")
except APITimeoutError:
    print("Request timed out. Please retry.")

`APIConnectionError`

Connection to Noukai failed.

Code: api_connection
HTTP Status: N/A

Causes:

Network unreachable
DNS resolution failed
TLS handshake failed

Example:

try:
    result = await flow.execute(message="hello")
except APIConnectionError:
    print("Network error. Check your internet connection.")

`FlowExecutionError`

Flow execution failed.

Code: flow_execution_error
HTTP Status: 500

Causes:

LLM provider error
Step execution error
Invalid flow configuration

Attributes:

details (dict, optional): Additional error details from the flow

Example:

try:
    result = await flow.execute(message="hello")
except FlowExecutionError as e:
    print(f"Flow failed: {e.message}")
    if hasattr(e, 'details'):
        print(f"Details: {e.details}")

`ToolCallLimitError`

Tool calls exceeded retry limit.

Code: tool_call_limit
HTTP Status: N/A

Causes:

Tool execution failed repeatedly
All retries exhausted

Attributes:

tool_call_id (str, optional): ID of the failing tool call
attempt_count (int, optional): Number of attempts made

Example:

try:
    result = await flow.execute(
        message="hello",
        tools=[...],
        tool_handler=handler
    )
except ToolCallLimitError as e:
    print(f"Tool call failed after {e.attempt_count} attempts")

Error Codes Reference

Exception	Code	HTTP	When to handle
`AuthenticationError`	`authentication_error`	401	Check API key setup
`PermissionDeniedError`	`permission_denied`	403	User role / flow access
`FlowNotFoundError`	`flow_not_found`	404	Verify flow slug
`InsufficientCreditsError`	`insufficient_credits`	402	Billing / top-up
`RateLimitError`	`rate_limit_exceeded`	429	Implement backoff
`APITimeoutError`	`api_timeout`	504	Retry manually
`APIConnectionError`	`api_connection`	—	Check network
`FlowExecutionError`	`flow_execution_error`	500	Debug flow config
`ToolCallLimitError`	`tool_call_limit`	—	Fix tool handler

Error Handling Patterns

By Exception Type

from noukai_sdk import (
    FlowNotFoundError,
    InsufficientCreditsError,
    AuthenticationError,
    NoukaiError
)
 
try:
    result = await flow.execute(message="hello")
except FlowNotFoundError:
    # Handle missing flow
    pass
except InsufficientCreditsError:
    # Handle billing
    pass
except AuthenticationError:
    # Handle auth
    pass
except NoukaiError as e:
    # Handle other Noukai errors
    pass

By Error Code

try:
    result = await flow.execute(message="hello")
except NoukaiError as e:
    if e.code == "flow_not_found":
        # Handle missing flow
        pass
    elif e.code == "insufficient_credits":
        # Handle billing
        pass
    else:
        raise

With Retries

import asyncio
from noukai_sdk import APITimeoutError
 
async def execute_with_backoff(flow, message, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await flow.execute(message=message)
        except APITimeoutError:
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt  # Exponential backoff
            await asyncio.sleep(wait_time)

On this page