Error Reference
STACK returns errors in one JSON envelope. Branch on the machine-readable code. Show the message to the operator when it helps them fix the request.
Response shape
{
"error": {
"code": "PASSPORT_REVOKED",
"message": "Passport has been revoked",
"details": {}
}
}details is optional. Validation failures can use VALIDATION_ERROR, INVALID_JSON, EMPTY_BODY, or UNSUPPORTED_MEDIA_TYPE.
Common codes
code HTTP meaning
UNAUTHORIZED 401 authentication is missing or invalid
INVALID_API_KEY 401 the API key is not valid
AGENT_JWT_REPLAYED 401 a one-use agent JWT was sent again
PASSPORT_EXPIRED 401 the Passport token has expired
PASSPORT_REVOKED 401 the Passport has been revoked
FORBIDDEN 403 the caller cannot perform the action
OPERATOR_SUSPENDED 403 the operator is suspended
OPERATOR_DELETED 403 the operator was deleted
PASSPORT_BLOCKED 403 this agent cannot issue a new Passport
TIER_LIMIT_EXCEEDED 403 a plan resource limit was reached
TRUST_LEVEL_INSUFFICIENT 403 a skill trust requirement was not met
UNAUTHORIZED_SKILL_ACCESS 403 the agent may not invoke this skill
IDENTITY_REQUIREMENTS_NOT_MET 403 service identity requirements were not met
GOVERNANCE_APPROVAL_REQUIRED 403 a human step-up is required
INSUFFICIENT_CREDITS 402 the wallet cannot cover the charge
DELEGATION_DEPTH_EXCEEDED 400 the delegation depth would exceed four hops
SCOPE_ESCALATION 400 delegated scope is wider than parent scope
ACCOUNTABILITY_REQUIRED 400 required intent data is missing
DELEGATION_ACCOUNTABILITY_VIOLATION 400 delegation would use a looser mode
SCHEMA_VALIDATION_FAILED 400 skill or drop-off data failed its schema
CMEK_CONFIGURATION_INVALID 400 the customer KMS configuration is invalid
NOT_FOUND 404 the resource was not found for this caller
SKILL_NOT_FOUND 404 the skill was not found or is not active
INVOCATION_NOT_FOUND 404 the invocation was not found
CHECKPOINT_NOT_AVAILABLE 404 the Passport mode does not support this step
CONFLICT 409 the request conflicts with current state
DROPOFF_ALREADY_COLLECTED 409 the drop-off was already consumed
DROPOFF_EXPIRED 410 the drop-off expired
INVOCATION_EXPIRED 410 the skill invocation expired
SERVICE_UNAVAILABLE 503 a required service is temporarily unavailable
CMEK_REVOKED 503 STACK cannot use the configured customer KMS keyRetry rules
- Do not retry an expired or revoked Passport. Issue a new Passport.
- Do not resend an agent JWT. Sign a new JWT for each request and retry.
- Correct 400 responses before retrying.
- Resolve 402 and 403 responses before retrying.
- Treat 409 and 410 as terminal for the named resource.
- Retry 503 responses with bounded exponential backoff and jitter.
Governance step-up
GOVERNANCE_APPROVAL_REQUIRED means the action did not run. Show the returned approval URL to a human. After approval, repeat the same request with X-Governance-Approval set to the approval ID. The approval is single-use, expires after 15 minutes, and is bound to the request payload.
Schema failures
SCHEMA_VALIDATION_FAILED includes validation errors in details.errors. Correct the data to match the published skill schema or the drop-off schema.
Unexpected server failures return INTERNAL_ERROR with HTTP 500. The response does not include internal exception details.