SDK Reference

Java: Error handling

Overview

Catch typed ZofApiError with code, message, and param fields for validation failures.

Retry idempotent GET requests on 5xx with exponential backoff; do not blindly retry POST without idempotency keys.

Who should read this

  • QA engineers, SREs, platform teams, and developers operating Zof Console and APIs.

Prerequisites

  • Java runtime installed
  • Organization API key

When to use this workflow

  • Onboarding new team members to Zof terminology and workflows
  • Authoring internal runbooks aligned with Console labels
  • Designing CI/CD or webhook integrations against documented behavior

Step-by-step procedure

Confirm access

Verify organization membership and role permissions in Admin Center.

Confirm API key or SSO session is scoped to the correct tenant.

Apply this guidance

Follow Console navigation paths and API examples in this document.

Use staging project and environment IDs for first-time integration tests.

Verify outcomes

Check Operate → Runs, Quality areas, or API responses for expected results.

Update team runbooks when your stack requires environment-specific variations.

Key concepts

Organization scope
All Zof Console and API operations are isolated to your authenticated tenant.
Governed execution
Agent output and remediation follow policy packs with human approval when configured.

Best practices

  • Validate changes in staging before applying release gates to production.
  • Include run IDs and timestamps when escalating issues to support or auditors.
  • Align internal runbook terminology with Zof Console UI labels for clarity.

Common issues

rate_limit_exceeded
Sleep for retryAfterMs then retry; reduce poll frequency.
invalid_request
Check error.param for field name; validate against API docs.

Example

try {
  await client.runs.create(payload);
} catch (e) {
  if (e.code === 'rate_limit_exceeded') await sleep(e.retryAfterMs);
}

Was this page helpful?

Java: Error handling | Zof AI Documentation