Error Codes¶

ACGP error codes and troubleshooting.

Error Code Format¶

ACGP-XXXX: Error description

Common Errors¶

ACGP-1001: Invalid Trace Format¶

Cause: Cognitive trace is malformed or missing required fields

Solution: - Check trace has reasoning, action, and parameters - Validate JSON structure - See Cognitive Traces

ACGP-1002: Authentication Failed¶

Cause: Invalid API key or certificate

Solution: - Verify API key is correct - Check certificate expiration - Confirm endpoint URL

ACGP-1003: ACL Tier Invalid¶

Cause: ACL tier not recognized

Solution: - Use valid tier: ACL-0 through ACL-5 - Check for typos

ACGP-2001: Evaluation Timeout¶

Cause: Evaluation took too long

Solution: - Simplify trace - Check network latency - Consider lower ACL tier

ACGP-3001: Tripwire Exceeded¶

Cause: Action exceeded defined limit

Solution: - Review tripwire configuration - Check if limit is appropriate - Adjust parameters

ACGP-3002: Rate Limit Exceeded¶

Cause: Too many evaluation requests in time window

Solution: - Implement request queuing - Increase rate limit in configuration - Use batch evaluation for multiple traces

ACGP-3003: Trust Score Below Threshold¶

Cause: Agent trust score too low for requested action

Solution: - Review recent agent behavior - Check trust decay configuration - Consider resetting trust with supervision

ACGP-4001: Blueprint Not Found¶

Cause: Specified blueprint does not exist

Solution: - Check blueprint name spelling - Verify blueprint is registered - Use default blueprint if unsure

ACGP-4002: Blueprint Validation Failed¶

Cause: Blueprint YAML is malformed or invalid

Solution: - Validate YAML syntax - Check required fields are present - See Blueprint Schema

ACGP-4003: Blueprint Version Mismatch¶

Cause: Blueprint version incompatible with SDK

Solution: - Update SDK to latest version - Downgrade blueprint to compatible version - Check compatibility matrix

ACGP-5001: Cryptographic Verification Failed¶

Cause: Signature or hash verification failed (Complete conformance)

Solution: - Check key configuration - Verify certificate chain - Ensure HSM is accessible

ACGP-5002: Consensus Not Reached¶

Cause: Distributed stewards failed to reach agreement (Complete conformance)

Solution: - Check network connectivity between nodes - Verify quorum configuration - Review timeout settings

ACGP-5003: Audit Log Tampered¶

Cause: Audit log integrity check failed

Solution: - Investigate potential security breach - Restore from verified backup - Contact security team

ACGP-6001: Context Window Exceeded¶

Cause: Cognitive trace too large for evaluation

Solution: - Reduce reasoning length - Summarize context - Split into multiple traces

ACGP-6002: Unsupported Action Type¶

Cause: Action type not recognized by blueprint

Solution: - Check action name in blueprint - Register custom action type - Use generic action category

ACGP-6003: Invalid Parameter Format¶

Cause: Action parameters don't match expected schema

Solution: - Check parameter types - Validate against blueprint schema - See action documentation

ACGP-7001: Steward Unavailable¶

Cause: Governance steward service is down

Solution: - Check service health - Implement fallback policy - Use local caching if available

ACGP-7002: Network Timeout¶

Cause: Request to steward timed out

Solution: - Check network connectivity - Increase timeout configuration - Consider lower ACL tier for faster response

ACGP-7003: Service Overloaded¶

Cause: Steward service at capacity

Solution: - Implement exponential backoff - Queue non-critical evaluations - Scale steward instances

Error Categories¶

Code Range	Category	Description
ACGP-1xxx	Validation	Input validation errors
ACGP-2xxx	Evaluation	Evaluation process errors
ACGP-3xxx	Policy	Policy and limit violations
ACGP-4xxx	Blueprint	Blueprint-related errors
ACGP-5xxx	Security	Security and cryptographic errors
ACGP-6xxx	Format	Data format and size errors
ACGP-7xxx	Infrastructure	Service and network errors

Handling Errors in Code¶

from acgp import GovernanceSteward, ACGPError, TripwireError, ValidationError

steward = GovernanceSteward(acl_tier="ACL-2")

try:
    result = steward.evaluate(trace)
except ValidationError as e:
    # Handle input validation issues
    log.error(f"Invalid trace: {e.code} - {e.message}")
except TripwireError as e:
    # Handle policy violations
    log.warning(f"Tripwire triggered: {e.tripwire_name}")
    escalate_to_human(trace)
except ACGPError as e:
    # Handle all other ACGP errors
    log.error(f"ACGP error: {e.code} - {e.message}")
    apply_fallback_policy(trace)

Glossary Troubleshooting