# Credential states and errors

> Operational reference for status, version states, setup failures, binding failures, and authorization recovery.

Use machine error codes when available and human messages for context. Do not retry a mutation merely because transport failed; follow the provider's recovery and the operation's returned state.

## Credential status {#credential-status}

| Status | Operator meaning |
| --- | --- |
| Pending | Creation, mint, or authorization has not completed |
| Active | At least one usable active version exists |
| Inactive | No version is currently injectable |
| Failed | Initial acquisition failed and no active version exists |

Version states are documented in [Credential lifecycle](/docs/credentials/lifecycle.md#version-states).

## Common setup failures {#setup-failures}

| Symptom | Likely cause | Action |
| --- | --- | --- |
| Provider package unavailable | Wrong tenant visibility or obsolete package | Refresh catalog or upload a current private package |
| Configuration rejected | Field missing, wrong type, or unknown property | Follow field help and package schema |
| Bootstrap Credential conflict | Reused generated identity or incompatible existing target | Use a new provider name or select the intended Credential |
| Provider has incomplete operations | Package probe and declared authorization disagree | Fix and rebuild the package |

## Binding failures {#binding-failures}

| Code | Meaning |
| --- | --- |
| `BindingRequired` | No Resource assignment exists for the exact owner |
| `CredentialBindingRequired` | No Credential assignment exists for a required Resource slot |
| `BindingUnavailable` | Assignment is missing, disabled, malformed, or registry resolution is incomplete |
| `BindingUseDenied` | Policy denied `binding:use` |
| `BindingOwnerMismatch` | Authenticated owner and target tenant boundary disagree |
| `BindingTargetUnavailable` | The exact pinned target version cannot be loaded |
| `BindingContractMismatch` | Resource Driver or operation catalog differs from the authored contract |

## Credential use failures {#credential-use-failures}

| Code or status | Meaning |
| --- | --- |
| `CredentialUnavailable` | No usable active version exists |
| `CredentialRevoked` | Requested authority was permanently revoked |
| Policy denial | The authenticated run cannot use this Credential |
| Verification rejected | Candidate material was not activated |

## Authorization recovery {#authorization-recovery}

Restart authorization when state expired, consent was denied, refresh state expired, or an uncertain single-use exchange cannot prove its outcome. Never replay a callback code or refresh token. Existing active material remains usable only when provider policy and its expiry permit it.