Error Codes
Stable B3IQ error envelopes and machine-readable codes for hosted gateway, local APIs, routing, billing, 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, billing policy, 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, protocol, model, benchmark, and policy gates |
| router_dispatch_failed | Selected route did not return a usable response |
| insufficient_balance | Customer balance cannot reserve the quoted job |
| gateway_spend_cap_exceeded | Customer rolling spend cap would be exceeded |
| model_benchmark_unverified | Profile benchmark proof is missing |
| observed_benchmark_missing | Control-plane observed benchmark proof is missing for a billable path |
| protocol_stake_unsatisfied | Node does not satisfy stake policy |
| 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, billing, model readiness,
route-readiness, and support workflows.
Avoid
Parse titles
Human-readable titles can change. Stable machine codes are the compatibility contract.