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

# Error Codes

Stable B3IQ error envelopes and machine-readable codes for hosted gateway, local APIs, routing, rate limits, quotas, model readiness, protocol eligibility, and private jobs.

B3IQ endpoints use stable machine-readable error codes so clients can distinguish
auth failures, model blockers, route selection failures, quota and rate-limit
denials, and private-job issues.

## OpenAI-compatible envelope

Hosted OpenAI-compatible endpoints return an OpenAI-style `error` object with a
B3IQ detail object.

```json
{
  "error": {
    "message": "human readable detail",
    "type": "invalid_request_error",
    "param": null,
    "code": "stable_machine_code",
    "b3iq": {
      "status": 400,
      "title": "B3IQ title",
      "detail": "human readable detail",
      "code": "stable_machine_code"
    }
  }
}
```

## Native problem envelope

B3IQ-native endpoints return problem JSON:

```json
{
  "error": {
    "status": 400,
    "title": "B3IQ title",
    "detail": "human readable detail",
    "code": "stable_machine_code"
  }
}
```

## Common codes

| Code | Meaning |
| --- | --- |
| ` unauthorized ` | Missing or invalid bearer, admin, customer, router, or local credential |
| ` gateway_api_key_scope_denied ` | Hosted gateway key lacks required scope |
| ` no_healthy_candidates ` | No route passed liveness, tunnel, runtime, model, benchmark, and policy gates (503) |
| ` no_eligible_nodes ` | The key resolves no machine that could serve the request: 404 when the account or key scope has no machine at all, and also carried as the `code` on the 503 above when your machines exist but none are healthy for this request |
| ` account_token_quota_exceeded ` | The account's daily token quota is exhausted (429). It resets at midnight UTC; the default quota is uncapped |
| ` model_benchmark_unverified ` | Profile benchmark proof is missing |
| ` observed_benchmark_missing ` | Control-plane observed benchmark proof is missing for a network-routed profile (own-machine dispatch is exempt) |
| ` invalid_encrypted_request ` | Private-job encrypted request payload is malformed |
| ` receipt_hash_mismatch ` | Submitted receipt hash does not match signed payload |
| ` invalid_signature ` | Node or customer signed payload did not verify |

## HTTP status mapping

| HTTP status | OpenAI-compatible type |
| --- | --- |
| ` 400, 413, 415 ` | ` invalid_request_error ` |
| ` 401, 403 ` | ` authentication_error ` |
| ` 402 ` | ` insufficient_quota ` |
| ` 404 ` | ` not_found_error ` |
| ` 409 ` | ` conflict_error ` |
| ` 429 ` | ` rate_limit_error ` |
| ` 5xx ` | ` api_error ` |

## Client guidance

**Branch on code**

Use `error.code` or `error.b3iq.code` for retry, quota, model readiness,
    route-readiness, and support workflows.
  **Parse titles**

Human-readable titles can change. Stable machine codes are the compatibility
    contract.