Errors

Overview

The API returns conventional HTTP status codes and a structured JSON error object with code, message, and optional param field for validation failures.

Who should read this

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

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

Key concepts

400 Bad Request

Malformed JSON, missing required field, or invalid parameter value.

401 Unauthorized

Missing, expired, or invalid API key.

403 Forbidden

Valid key but insufficient role permission for the operation.

404 Not Found

Resource ID unknown or not visible in your organization scope.

409 Conflict

State conflict, e.g., canceling a completed run.

429 Too Many Requests

Rate limit exceeded; honor Retry-After header.

500 Internal Server Error

Transient server fault; retry idempotent GETs with backoff.

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

401 after key rotation

Update CI secrets with new key; revoke old key only after cutover.

403 on run create

Key owner role may lack runs:create; use service account with QA or admin role.

Error response shape

{
  "error": {
    "code": "invalid_request",
    "message": "environment must be one of: staging, production",
    "param": "environment"
  }
}