Errors
Every problem code the API answers, and what to do about each.
Errors are application/problem+json (RFC 9457) with a stable code, a human detail, usually a hint with the fix in-band, and a docs_url. If your integration switches on anything, switch on code.
{
"type": "https://api.bixel.com/problems/key_required",
"title": "API key required",
"status": 401,
"code": "key_required",
"detail": "Change-event values require a free API key.",
"hint": "Sign in and mint a free key at https://bixel.com/account/ — the open tier needs none.",
"docs_url": "https://bixel.com/docs/api"
}The codes
| Code | Status | What happened | What to do |
|---|---|---|---|
company_not_found | 404 | No company matches the identifier | Resolve names via GET /v1/search?q= — identifiers are apex domains |
invalid_identifier | 400 | Not a valid domain or slug | Use the apex domain, e.g. /v1/companies/pinecone.io |
category_not_found | 404 | No category matches the slug | List slugs via GET /v1/categories |
missing_parameter | 400 | A required query parameter is absent | The detail names it |
invalid_parameter | 400 | A parameter failed validation | The detail carries the accepted values |
invalid_cursor | 400 | The pagination cursor was altered | Pass meta.next_cursor back exactly as received |
key_required | 401 | A keyed capability was called keyless | Mint a free key at bixel.com/account — the open tier needs none |
invalid_key | 401 | The key is unknown, revoked, or expired | Check it, or mint a new one |
rate_limited | 429 | A window is exhausted | Honor Retry-After; RateLimit-Policy shows both windows |
upgrade_required | 403 | A Pro capability on a free credential (the 365-day trajectory window, full change-event depth) | Upgrade at bixel.com/pricing; free keys keep current state + 90 days of history values |
not_yet_available | 501 | A reserved parameter is specified but not served yet | Drop the parameter; it will light up without a contract change |
fact_not_found | 404 | The company has no current fact with that key | List keys via GET /v1/companies/{company}/facts |
proof_not_available | 404 | The fact has no stored capture behind it | Expected for fed-forward network signals; not an error to retry |
proof_not_yet_anchored | 503 | The capture postdates the last anchored export | Retry after the next twice-weekly anchoring run (Retry-After is set) |
proof_unavailable | 503 | The evidence store could not be reached | Transient; retry shortly |
Reading 401 vs 403 on MCP
A keyless or dead-credential MCP request answers 401 with OAuth discovery metadata — that is the sign-in trigger, not a failure. A 403 upgrade_required means the credential authenticated fine and the account tier is the only thing standing; agents should relay the hint rather than retry.