Error Codes¶

Kiket surfaces structured error codes for API responses and sync jobs. Use this reference to diagnose issues quickly.

API Error Format¶

{
  "error": "validation_error",
  "message": "Transition not allowed",
  "code": "WORKFLOW_TRANSITION_GUARD_FAILED",
  "details": [
    {
      "field": "state",
      "message": "Transition from review to done requires approval"
    }
  ]
}

Common Codes¶

Code	Description	Resolution
`AUTH_INVALID_TOKEN`	Token missing or expired	Refresh or reauthenticate
`AUTH_FORBIDDEN_SCOPE`	Token lacks required scope	Request token with additional scopes
`PROJECT_NOT_FOUND`	Project slug does not exist	Verify slug or permissions
`ISSUE_NOT_FOUND`	Issue key invalid	Check key and project
`WORKFLOW_NOT_FOUND`	Workflow key missing	Ensure `.kiket/workflows` contains the file
`WORKFLOW_TRANSITION_GUARD_FAILED`	Guard prevented transition	Review workflow YAML guard conditions
`BOARD_SCHEMA_INVALID`	Board YAML failed validation	Inspect sync logs for details
`EXTENSION_INSTALL_FAILED`	Manifest or endpoint invalid	Validate manifest, check logs
`RATE_LIMIT_EXCEEDED`	Request quota reached	Back off, inspect `Retry-After`

Sync Job Errors¶

sync.invalid_yaml – YAML parsing failed; check indentation and schema.
sync.unauthorized – GitHub credentials invalid or missing scopes.
sync.not_found – .kiket/ directory or files missing on the branch.
sync.merge_conflict – Workflow cache update encountered conflicts; rerun after resolving.

CLI Exit Codes¶

0 – Success
1 – General failure
2 – Validation errors (details printed to stdout)
3 – Authentication failure

Consult project logs (log/production.log) or Cloud Logging for stack traces when errors persist.