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 |
invalid_body | 400 | The JSON body failed validation | The detail names the field |
companies_unresolved | 400 | Some identifiers in a batch match no covered company; nothing was created | The detail lists them; resolve names via GET /v1/resolve first |
account_key_required | 403 | Watch and claim resources belong to an account; the credential has no owning account | Use a key minted at bixel.com/account, or sign in through the connector |
watch_limit_reached | 403 | Your plan's watch capacity (endpoints or watched companies) is used up | Compare plans at bixel.com/pricing |
subscription_not_found | 404 | No watch subscription with that id on this account | GET /v1/watch/subscriptions |
endpoint_not_found | 404 | No webhook endpoint with that id on this account | GET /v1/watch/endpoints |
delivery_not_found | 404 | No webhook delivery with that id on this account | GET /v1/watch/endpoints/{id}/deliveries |
claim_not_found | 404 | No domain claim with that id on this account | GET /v1/claims |
claim_not_verified | 409 | Declarations need a verified claim | Complete the method's proof, then POST /v1/claims/{id}/verify |
claim_verification_failed | 422 | The proof for the claim was not found | DNS can take up to an hour to propagate; retry |
claim_domain_not_covered | 422 | The domain does not resolve to a Bixel brand yet | GET /v1/resolve?domain= first; request coverage if it is unresolved |
claim_limit_reached | 403 | Too many pending claims on the account | Verify or let pending claims age out |
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 |
rate_limiter_unavailable | 503 | The limit store is unreachable, so keyless calls fail closed | Transient; honor Retry-After (keyed calls are unaffected) |
credits_exhausted | 429 | The account's monthly credits and pay-as-you-go balance are both spent | Top up or raise the cap at bixel.com/account/billing; the reset moment is the X-Bixel-Credits-Reset header |
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 |
capture_not_found | 404 | No capture matches that id | Take capture ids from fact payloads, never construct them |
raw_not_stored | 404 | The capture predates raw storage | Expected for the earliest era; the manifest row still verifies |
capture_integrity_error | 503 | The stored bytes failed their own hash check on read | Never served silently; report it if you see one |
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.