Version: Current
Historical release snapshot. These docs are frozen. Read current docs.
Error codes
A code is the stable thing a caller branches on. It is the same string in every dialect, so a client can switch on it without parsing prose.
Source: acumen:internal/protocol/errtaxonomy/taxonomy.go.
Source revision: 83fbd00.
Declared paths: internal/protocol/errtaxonomy/taxonomy.go.
Provenance: each row cites the taxonomy definition line (Defined at) and the catalogue metadata line (Meta at) when available.
HTTP mapping comes from the taxonomy status. gRPC mapping is not declared in this taxonomy; gateway/door transports map codes to protocol errors at the edge, so gRPC status is transport-specific and not fabricated here. Retry/action guidance: see the companion Error actions page for operator/developer steps.
62 codes in 9 classes.
| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
auth_missing |
401 | no | RetryAfterNone |
Missing credentials | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:73 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:216 |
auth_invalid |
401 | no | RetryAfterNone |
Invalid credentials | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:74 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:217 |
auth_revoked |
401 | no | RetryAfterNone |
Credential revoked | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:75 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:218 |
auth_expired |
401 | no | RetryAfterNone |
Credential expired | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:76 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:219 |
auth_scope |
403 | no | RetryAfterNone |
Credential lacks the required scope | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:77 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:220 |
auth_process_token |
403 | no | RetryAfterNone |
Process token is not accepted on this door | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:78 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:221 |
auth_session |
401 | no | RetryAfterNone |
Session is not valid | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:79 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:222 |
creds_seat_side_only |
401 | no | RetryAfterNone |
Vendor credentials are accepted seat-side only | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:144 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:223 |
rate_limit
Section titled “rate_limit”| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
rate_rpm |
429 | yes | RetryAfterFloor1s |
Request rate limit exceeded | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:82 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:226 |
rate_tpm |
429 | yes | RetryAfterFloor1s |
Token rate limit exceeded | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:83 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:227 |
rate_concurrency |
429 | yes | RetryAfterFloor1s |
Concurrency limit exceeded | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:84 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:228 |
rate_tenant |
429 | yes | RetryAfterFloor1s |
Tenant rate limit exceeded | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:85 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:229 |
rate_ip |
429 | yes | RetryAfterFloor1s |
Source IP rate limit exceeded | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:86 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:230 |
limit_exceeded |
429 | yes | RetryAfterFloor1s |
Seat allowance exceeded | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:87 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:231 |
budget
Section titled “budget”| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
budget_key_daily |
402 | no | RetryAfterCallerWindow |
Key daily budget exhausted | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:90 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:234 |
budget_key_weekly |
402 | no | RetryAfterCallerWindow |
Key weekly budget exhausted | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:91 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:235 |
budget_key_monthly |
402 | no | RetryAfterCallerWindow |
Key monthly budget exhausted | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:92 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:236 |
budget_project |
402 | no | RetryAfterNone |
Project budget exhausted | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:93 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:237 |
budget_tenant |
402 | no | RetryAfterNone |
Tenant budget exhausted | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:94 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:238 |
budget_seat |
402 | no | RetryAfterNone |
Seat budget exhausted | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:95 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:239 |
budget_pool_exhausted |
402 | no | RetryAfterNone |
Budget pool exhausted | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:96 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:240 |
budget_reservation_failed |
402 | no | RetryAfterNone |
Budget reservation failed | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:97 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:241 |
wallet_floor_refused |
402 | no | RetryAfterNone |
Wallet balance at or below the configured floor | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:98 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:242 |
gateway
Section titled “gateway”| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
wallet_balance_stale |
503 | no | RetryAfterNone |
Wallet balance unavailable | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:99 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:293 |
internal |
500 | no | RetryAfterNone |
Internal gateway error | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:133 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:281 |
store_unavailable |
503 | yes | RetryAfterDefault1s |
Store unavailable | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:134 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:282 |
store_schema_mismatch |
503 | yes | RetryAfterDefault1s |
Store schema is incompatible with this binary | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:135 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:283 |
overloaded |
503 | yes | RetryAfterDefault1s |
Gateway overloaded | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:136 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:284 |
draining |
503 | yes | RetryAfterDefault1s |
Gateway draining | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:137 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:285 |
not_implemented |
501 | no | RetryAfterNone |
Not implemented | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:138 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:286 |
secrets_not_accepted |
400 | no | RetryAfterNone |
Secret value supplied where a reference is required | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:139 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:287 |
seat_reauth_required |
503 | no | RetryAfterNone |
Seat credential needs operator re-authentication | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:145 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:288 |
seat_credential_missing |
503 | no | RetryAfterNone |
Seat has no stored credential | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:146 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:289 |
seat_credential_unavailable |
503 | no | RetryAfterNone |
Seat credential cannot be used right now | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:147 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:290 |
cli_oauth_disabled |
503 | no | RetryAfterNone |
CLI-OAuth and CLI-exec seats are disabled for this provider | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:148 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:291 |
base_url_rejected |
503 | no | RetryAfterNone |
Seat base URL was rejected by the egress policy | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:149 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:292 |
budget_unavailable |
503 | no | RetryAfterNone |
Budget ledger unavailable; an enabled hard cap refuses rather than allows | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:150 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:294 |
byok_unavailable |
503 | no | RetryAfterNone |
No usable BYOK credential for this provider; the system credential is never substituted | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:151 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:295 |
model_unavailable
Section titled “model_unavailable”| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
model_unknown |
404 | no | RetryAfterNone |
Unknown model | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:103 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:246 |
model_not_found |
404 | no | RetryAfterNone |
Model not found | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:104 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:247 |
model_not_allowed |
403 | no | RetryAfterNone |
Model not allowed for this credential | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:105 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:248 |
model_no_eligible_seat |
503 | yes | RetryAfterNone |
No eligible seat can serve this model | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:106 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:249 |
model_catalog_stale |
503 | yes | RetryAfterCallerWindow |
Model catalog is stale | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:107 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:250 |
model_deprecated |
410 | no | RetryAfterNone |
Model deprecated | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:108 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:251 |
model_capability_unsupported |
400 | no | RetryAfterNone |
Model does not support the requested capability | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:109 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:252 |
contract
Section titled “contract”| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
contract_unsupported |
400 | no | RetryAfterNone |
Unsupported contract version | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:112 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:255 |
schema_invalid |
400 | no | RetryAfterNone |
Request body failed schema validation | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:113 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:256 |
payload_too_large |
413 | no | RetryAfterNone |
Request payload too large | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:114 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:257 |
unsupported_media_type |
415 | no | RetryAfterNone |
Unsupported media type | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:115 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:258 |
precondition_failed |
412 | no | RetryAfterNone |
Precondition failed | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:116 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:259 |
idempotency
Section titled “idempotency”| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
idempotency_in_flight |
409 | yes | RetryAfterDefault1s |
Idempotent request already in flight | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:119 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:262 |
idempotency_conflict |
409 | no | RetryAfterNone |
Idempotency key reused with a different body | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:120 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:263 |
idempotency_stream_completed |
409 | no | RetryAfterNone |
Idempotent stream already completed | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:121 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:264 |
idempotency_replay_unavailable |
422 | no | RetryAfterNone |
Idempotent replay is no longer available | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:122 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:265 |
upstream
Section titled “upstream”| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
upstream_error |
502 | yes | RetryAfterVendorClamped |
Upstream provider returned an error | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:125 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:273 |
upstream_timeout |
504 | yes | RetryAfterVendorClamped |
Upstream provider timed out | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:126 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:274 |
upstream_rate_limited |
429 | yes | RetryAfterVendorClamped |
Upstream provider rate limited the seat | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:127 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:275 |
upstream_auth |
502 | yes | RetryAfterVendorClamped |
Upstream rejected the seat credential | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:128 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:276 |
upstream_empty |
502 | yes | RetryAfterVendorClamped |
Upstream returned an empty response | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:129 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:277 |
upstream_protocol |
502 | yes | RetryAfterVendorClamped |
Upstream violated the expected protocol | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:130 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:278 |
not_found
Section titled “not_found”| Code | HTTP | Retryable | Retry-After policy | Summary | gRPC mapping | Defined at | Meta at |
|---|---|---|---|---|---|---|---|
resource_not_found |
404 | no | RetryAfterNone |
Resource not found | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:154 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:298 |
route_not_found |
404 | no | RetryAfterNone |
Route not found | transport-specific (not declared in taxonomy) | acumen:internal/protocol/errtaxonomy/taxonomy.go:155 |
acumen:internal/protocol/errtaxonomy/taxonomy.go:299 |