Skip to content

Errors and troubleshooting

The SDK maps transport and API failures to skyportalai exceptions.

Exception hierarchy

SkyportalError
├── APIConnectionError
├── WaitTimeoutError
└── APIStatusError
    ├── AuthenticationError
    └── APIError

Example handling:

from skyportalai import (
    APIConnectionError,
    APIError,
    AuthenticationError,
    Skyportal,
    WaitTimeoutError,
)

try:
    with Skyportal() as client:
        chat = client.chat.create_chat("Check service health", server_id=42)
        chat.wait(timeout=120)
except AuthenticationError:
    print("The API credential was missing or rejected")
except APIConnectionError:
    print("SkyPortal could not be reached")
except WaitTimeoutError:
    print("The workflow is still running")
except APIError as error:
    print(error.status_code, error.body)

Retry behavior

  • Only GET requests are retried.
  • Network failures, timeouts, and HTTP 5xx responses are retryable.
  • Default retry budget is 2 after initial attempt.
  • Backoff starts at 0.5 seconds and doubles.
  • Mutating requests are never auto-retried.

CLI exit codes

Code Meaning
0 Command completed successfully
1 Config, auth, connection, API, or workflow error
2 Awaiting approval, missing args, conflicting options, or CLI validation/usage error

If automation receives exit code 2 with awaiting_approval, request human review instead of retrying blindly.

Common checks

  1. Confirm SKYPORTAL_API_KEY is set for SDK/CLI usage.
  2. Validate --base-url placement before subcommands in skyportalai.
  3. Ensure timeouts are greater than zero.
  4. Confirm chat IDs and approval IDs are current.
  5. Use skyportalai --json when integrating with machine parsers.