Error Codes

Complete stable vocabulary of error codes. Branch on error.code, not on HTTP status.

For the error envelope and retry semantics, see Errors.

Envelope#

json
{
  "error": {
    "code": "secret_not_found",
    "message": "Secret 'environments/production/missing' not found",
    "details": {"path": "environments/production/missing"},
    "request_id": "req_abc"
  }
}

Authentication / authorization#

HTTP	Code	Meaning
401	`authentication_required`	Missing Authorization header
401	`token_expired`	Token `exp` passed
401	`token_invalid`	Signature failed
401	`token_revoked`	Explicitly revoked
403	`access_denied`	No matching policy rule
403	`insufficient_scope`	Token scope too narrow
403	`mfa_required`	Rule requires fresh MFA
403	`ip_not_allowed`	IP outside allowed ranges
403	`time_window_violation`	Outside time window
403	`tenant_access_denied`	Cross-tenant without partner admin
403	`forbidden`	Generic authorization failure

Validation#

HTTP	Code	Meaning
400	`invalid_request`	Malformed JSON or shape
400	`invalid_path`	Path format violation
400	`invalid_secret_type`	Unknown secret_type
400	`invalid_duration`	Duration string didn't parse
400	`invalid_cursor`	Cursor expired or malformed
400	`invalid_policy`	Policy rules/bindings invalid
400	`invalid_glob`	Path pattern not a valid glob
400	`invalid_role`	Role name invalid
400	`invalid_config`	Engine/backend config rejected
422	`validation_error`	Field-level validation; see `details.fields`

Not found#

HTTP	Code
404	`secret_not_found`
404	`version_not_found`
404	`policy_not_found`
404	`binding_not_found`
404	`webhook_not_found`
404	`subscription_not_found`
404	`rotation_policy_not_found`
404	`secret_policy_not_found`
404	`ca_not_found`
404	`certificate_not_found`
404	`csr_not_found`
404	`trust_anchor_not_found`
404	`acme_account_not_found`
404	`acme_order_not_found`
404	`dns_provider_not_found`
404	`engine_not_found`
404	`role_not_found`
404	`lease_not_found`
404	`tenant_not_found`
404	`identity_not_found`
404	`federation_backend_not_found`
404	`export_not_found`

Conflict / state#

HTTP	Code	Meaning
409	`secret_exists`	Soft-deleted path in retention
409	`version_conflict`	Concurrent modification
409	`policy_in_use`	Policy has bindings
409	`engine_in_use`	Engine has leases
409	`ca_has_certificates`	CA has issued certs
409	`name_conflict`	Name already taken
409	`binding_conflict`	Identity already bound
410	`secret_expired`	`expires_at` passed
410	`lease_expired`	Lease already expired

Rate limit / quota / availability#

HTTP	Code	Meaning
429	`rate_limited`	Caller-specific rate limit
429	`quota_exceeded`	Hard tenant quota
503	`service_unavailable`	Transient dependency outage
503	`feature_disabled`	Feature gated off at deploy
503	`maintenance_mode`	Operator-scheduled downtime

Server / backend#

HTTP	Code	Meaning
500	`internal_error`	Unexpected server error
500	`encryption_error`	KMS interaction failed
500	`storage_error`	Database or object store error
502	`backend_error`	Federated backend or ACME upstream failed
502	`backend_rate_limited`	Federated/ACME backend rate-limited us
504	`backend_timeout`	Federated backend timeout

Dynamic / PKI specific#

HTTP	Code	Meaning
400	`ttl_exceeds_max`	Requested TTL > role max_ttl
400	`domain_not_allowed`	CN/SAN not in role's allowed_domains
400	`key_type_mismatch`	CSR key doesn't match role requirement
400	`csr_invalid`	CSR failed to parse
409	`csr_already_processed`	CSR already signed or rejected
502	`acme_order_failed`	ACME upstream rejected order
502	`engine_unreachable`	Can't reach backend system

Webhook delivery#

HTTP (reported)	Code	Meaning
400	`webhook_url_invalid`	URL can't be used (private IP blocked, etc.)
502	`webhook_delivery_failed`	Non-2xx from destination
504	`webhook_delivery_timeout`	> 10s response time

Headers#

On every response:

X-Request-ID: req_abc — include in support tickets.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

On 429:

Retry-After: 45 — seconds.

Errors — semantics.
Rate Limiting — per-category caps.

Error Codes

Envelope#

Authentication / authorization#

Validation#

Not found#

Conflict / state#

Rate limit / quota / availability#

Server / backend#

Dynamic / PKI specific#

Webhook delivery#

Headers#

Related#