Error Types
Use stable types as your branch key
This page focuses on the taxonomy itself: how ProfileClaw names failures, how those categories should shape orchestration, and how to keep automation aligned with contract-level error codes.
`type` is the contract. `error` is support text.
If your runtime branches on prose, it will drift. If it branches on machine-readable type, it will stay aligned with the API surface.
What This Page Covers
Use Error Types when you are designing machine behavior, SDK branching, or retry policy inputs.
Taxonomy
Understand the naming model behind auth, validation, resource, rate-limit, and server failures.
- Treat each type family as a durable branch surface.
- Avoid string-matching the human-readable `error` field.
- Keep orchestration logic typed and explicit.
Recovery Planning
Decide which categories retry, which reconfigure, and which stop immediately.
- Retry rate-limit and some transient server failures.
- Fix input before replaying validation failures.
- Treat auth and scope failures as setup issues.
Contract Alignment
Use OpenAPI `x-error-codes` and typed clients to keep docs, tooling, and runtime behavior in sync.
- Enumerate expected codes before shipping.
- Test branches with fixture payloads.
- Investigate undocumented codes as drift signals.
Model error handling by category, not endpoint mood
Most failures fall into a few reusable families. That means your runtime can classify the failure once, then apply a consistent policy across many endpoints.
- Auth and scope failures usually mean the runtime must reconfigure credentials.
- Validation failures mean the request shape or input is wrong and must change first.
- Rate-limit and transient server failures are the main retry candidates.
Keep typed branching separate from user-facing copy
A strong integration can show clean product copy to users while still using raw typed envelopes for automation, debugging, and auditability.
- Map `type` to your own product copy at the app layer.
- Log the raw envelope for operators and incident review.
- Do not teach the model to improvise around wording changes.
Category Comparison
This table describes how the major error families should usually behave in a runtime.
| Category | Typical meaning | Default runtime move |
|---|---|---|
| Auth / Scope | The key is missing, invalid, or lacks the required capability. | Stop and reconfigure credentials or scopes. |
| Validation / Resource | The request is malformed, missing input, or refers to something unavailable. | Fix input or route selection before replaying. |
| Rate Limit / Server | The request is valid, but the system cannot serve it right now. | Retry with bounded backoff and observability. |
Decision Matrix
Use these rules to decide how the runtime should react when it receives a typed error.
Situation
You receive `rate_limit.exceeded`
Action
Wait, respect `Retry-After` if present, then retry with bounded backoff.
Why
The request may succeed later without changing input.
Situation
You receive a validation-specific type
Action
Stop the loop and change the request shape or missing fields first.
Why
Replaying the same invalid request only creates noise.
Situation
You receive an auth or forbidden type
Action
Treat it as a capability or secret configuration issue.
Why
The runtime, not the model, must repair credentials.
Representative envelopes
Use typed branches like these to drive the runtime.
{ "error": "Rate limit exceeded", "type": "rate_limit.exceeded"}{ "error": "Missing required field: targetRole", "type": "career_prediction.missing_target_role"}Next surfaces
After the taxonomy is clear, inspect the operational error flow and endpoint-specific codes.