API errors - bisibility

Errors use application/problem+json.

{
  "type": "https://bisibility.com/problems/validation_failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request input failed validation.",
  "instance": "urn:bisibility:api:v1:/api/v1/projects/prj_a00000000000000000000000/keywords",
  "docs_url": "https://bisibility.com/docs/api/errors#validation_failed",
  "errors": {}
}

Error codes

Code	HTTP status	Meaning
`bad_request`	400, 413, or 422	Request body, query, or JSON could not be parsed, payload is too large, or a required project input is unavailable.
`validation_failed`	400	Zod validation failed.
`invalid_cursor`	400	Pagination cursor is malformed or not a supported v3 cursor.
`invalid_public_id`	400	A path or payload ID is malformed, has the wrong resource prefix, or is not a public ID.
`unauthorized`	401	Missing or invalid bearer API key.
`unauthorized`	419	Instance import migration token is invalid, expired, or already used.
`forbidden`	403	API key scope or project scope does not allow the operation.
`not_found`	404	Route or resource was not found.
`method_not_allowed`	405	HTTP method is not handled by the router.
`conflict`	409	Request conflicts with the current resource state.
`self_import`	409	Instance import package was exported from the destination project itself.
`unsupported_api_version`	409	`Bisibility-API-Version` declares a version the server does not advertise.
`snapshot_expired`	409	No unexpired backlinks snapshot is available for the requested continuation.
`project_domain_required`	422	The operation requires a configured project domain.
`cost_limit_exceeded`	422	Estimated provider cost exceeds the request’s `max_cost_cents`.
`unsupported_target`	422	Backlinks target is not a supported site, subdomain, or page target.
`unsupported_location`	422	The provider cannot perform the requested lookup for that location.
`project_read_only`	423	Project writes are blocked by migration hold.
`budget_exhausted`	429	Monthly rank-check or provider budget is exhausted.
`lookup_in_progress`	429	An identical cached provider lookup is still running.
`rate_limited`	429	Request or upstream provider exceeded a rate limit.
`internal_server_error`	500	Unexpected API error.
`provider_unavailable`	400, 404, 422, or 502	Provider is not connected, needs authorization, rejects the request, or fails the lookup.
`scheduler_unavailable`	503	Async rank-check scheduler is unavailable.

Validation details

Validation errors include an errors member with the flattened Zod error payload:

{
  "fieldErrors": {
    "keyword": ["String must contain at least 1 character(s)"]
  },
  "formErrors": []
}

Rate-limit errors

Rate-limit responses include the same rate-limit headers as successful requests, plus Retry-After. Upstream provider rate limits also surface as rate_limited 429 responses with Retry-After.

Retry-After: 60
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 60