> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Taxonomy

> Understand Starfire AI error categories, what they mean, what should be retried, and what information to capture for support.

# Error taxonomy

Starfire errors should tell you **which subsystem failed and what kind of response is appropriate**. A useful error is more than a generic “something went wrong.”

## Error categories

| Category           | Typical meaning                                                        | Retry?                                              |
| ------------------ | ---------------------------------------------------------------------- | --------------------------------------------------- |
| Authentication     | Session or credential is missing, invalid, expired, or revoked.        | No, fix auth first                                  |
| Authorization      | Identity is valid but lacks permission.                                | No, fix access first                                |
| Validation         | Request or configuration is invalid.                                   | No, correct input                                   |
| Not found          | The referenced resource does not exist or is outside accessible scope. | Usually no                                          |
| Conflict           | Current resource state prevents the requested change.                  | After state changes                                 |
| Rate limit         | Too many requests or concurrent operations.                            | Yes, after delay/reset                              |
| Credit/usage limit | Billing or configured usage ceiling prevents new work.                 | After allowance changes/resets                      |
| Provider           | Upstream model/search/provider failed.                                 | Sometimes                                           |
| Timeout            | Work exceeded a request, tool, provider, or run timeout.               | Sometimes                                           |
| Build validation   | FORGE validator rejected generated/modified project state.             | Usually through repair workflow                     |
| Indexing           | Knowledge extraction, embedding, or indexing failed.                   | After source/provider issue is fixed                |
| Webhook delivery   | Starfire event existed but destination delivery failed.                | Delivery retries can apply                          |
| Internal platform  | Starfire subsystem failed unexpectedly.                                | Usually safe to retry once; investigate if repeated |

## Error information to capture

For a supportable error, collect:

* request ID
* resource ID such as run/build/artifact/project
* timestamp
* active account or organization context
* action being attempted
* visible error code/category
* whether retry changed the result

Do not include passwords, API keys, reset tokens, webhook secrets, or full payment details.

## Retry rules

Retry temporary conditions such as rate limits, provider failures, or transient service errors according to returned guidance.

Do not repeatedly retry invalid input, denied permissions, expired credentials, hard credit ceilings, or permanently failed resources.

## User-facing vs operator-facing errors

The user-facing message should explain what the user can do. Control Center can expose deeper diagnostics such as provider route, worker stage, reconciliation state, or failure metadata to authorized operators.

<Note>
  As the public Developer Platform stabilizes, endpoint-specific stable error codes can be added beneath this taxonomy without changing these higher-level categories.
</Note>