Troubleshooting and recovery
Use structured errors, request IDs, recovery fields, dry-runs, and idempotency keys so humans and agents can recover without unsafe retries.
Retry reads with backoff. Retry writes only with idempotency metadata or after a fresh dry-run.
Unauthorized
Refresh the token, verify scope, and never print the token value.
Lock conflict
List locks, identify the owner, and wait or ask for release before editing.
Rate limited
Back off. Use pagination and avoid repeated token minting loops.
Service unavailable
Record `requestId`, retry safe reads once, and escalate persistent failures.
Structured error fields
ForgeLore errors include `code`, `message`, `retryable`, `safeToRetry`, `requiredScope`, `requestId`, `nextAction`, `docsUrl`, and `recovery` when available.
Recovery commands
Agent recovery loop
- Read the structured error envelope.
- Stop immediately if `safeToRetry` is false.
- If a scope is missing, report the required scope and do not escalate privileges automatically.
- If a lock conflict exists, list locks and report the owner/path before changing assets.
- If retry is safe, use backoff and idempotency keys for writes.
When to escalate
Escalate after a safe retry fails, when `safeToRetry` is false, or when recovery requires a role change, force unlock, payment action, permanent deletion, secret access, or production infrastructure change. Include the error code and request ID, but never include credentials.