Error codes

Every machine-readable error code, its HTTP status, and what to do about it.

Every non-2xx response carries one of these codes in error.code (Errors and Conventions). Branch on the code; the message is for humans and may change.

Code	Status	Meaning · what to do
`INVALID_REQUEST`	400	Malformed body/query: unknown fields, missing `version`/`If-Match`, bad `X-Admin-Actor`, illegal replacement id, disabled record on make-default. Fix the request.
`AUTHENTICATION_REQUIRED`	401	Missing/invalid token for the plane: bad signature, wrong `iss`/`aud`, expired, non-canonical UUID `sub`, unmapped role. Get a fresh token (User Plane Tokens, Service Plane Tokens).
`FORBIDDEN`	403	Authenticated but not allowed: `auditor` on a mutation, non-manager on org credentials, `include_removed` without an elevated role, or a service token missing the required scope.
`VENDOR_NOT_FOUND`	404	No such vendor within your visibility (Vendors and Providers).
`PROVIDER_NOT_FOUND`	404	No such provider within your visibility.
`CREDENTIAL_NOT_FOUND`	404	No such credential owned by the addressed scope — someone else's record answers the same. Not retryable.
`CREDENTIAL_NOT_CONFIGURED`	404	Resolve walked every admitted level and found nothing. Configure a key or allow a fallback.
`PROVIDER_DISABLED`	409	The provider is disabled/removed in the catalog: no new credentials, no resolve.
`PROVIDER_DEPRECATED_FOR_NEW_CREDENTIALS`	409	Deprecated providers accept no new records; existing ones keep working. Migrate toward the replacement.
`DEFAULT_CREDENTIAL_ALREADY_EXISTS`	409	Two `make_default` creates raced for the same (provider, owner); the loser gets this. Retry once (Defaults and Lifecycle).
`CREDENTIAL_VERSION_CONFLICT`	409	Optimistic lock lost: your `version` is stale. Re-read, retry.
`OWNER_TYPE_NOT_ALLOWED_FOR_PROVIDER`	409	The provider's policy does not admit this ownership level at all.
`CREDENTIAL_SCHEMA_VALIDATION_FAILED`	422	The secret object violates `credential_schema` (Provider Schemas). Pointers in `details.errors`, values never echoed.
`CONFIGURATION_SCHEMA_VALIDATION_FAILED`	422	The configuration violates `configuration_schema`. Same shape.
`REQUEST_TOO_LARGE`	413	Body over 64 KiB.
`RATE_LIMITED`	429	A budget is exhausted; wait `Retry-After` seconds.
`CREDENTIAL_DECRYPTION_FAILED`	500	Stored ciphertext would not decrypt — a keyring incident, audited. Escalate to operators; do not retry blindly.
`INTERNAL_ERROR`	500	Unexpected failure. Report with the `correlation_id`.
`SERVICE_NOT_READY`	503	A dependency (database/keyring) is down — same facts as `GET /health/ready`. Retry after readiness.
`NOT_FOUND` / `METHOD_NOT_ALLOWED` / `HTTP_ERROR`	404/405/*	Generic HTTP-layer answers for unknown paths and methods.

A hands-on walk through the important ones: cookbook scenario 10.