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
Do
Branch on code
Use error.code or error.b3iq.code for retry, quota, model readiness,
route-readiness, and support workflows.
Avoid
Parse titles
Human-readable titles can change. Stable machine codes are the compatibility contract.