Errors

Every error is the same envelope — machine-stable code, human message, and a request_id to quote when reporting:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "recency must look like \"7d\" (1..365 days).",
    "request_id": "req_example",
    "doc_url": "https://docs.ariselabs-search-api.com/errors/invalid_parameter"
  }
}

How to react, by status

400 — fix the request; retrying unchanged cannot succeed.
401/403 — fix the key or scope.
402 — add credit before retrying.
409 — state-dependent (e.g. report_not_ready means keep polling).
429 — wait Retry-After, then retry with backoff if necessary.
5xx/503 — our side; retry with backoff.

Registered codes

code	http	note
`missing_parameter`	400	A required parameter is absent.
`invalid_parameter`	400	A parameter is unknown or malformed; the message names it and how to migrate.
`parameter_out_of_range`	400	The value is outside the documented range.
`unsupported_value`	400
`as_of_out_of_range`	400
`mode_unavailable`	400
`invalid_cursor`	400
`as_of_not_supported`	400
`conflicting_parameters`	400
`session_not_found`	404	No such research session for this org (ids are org-scoped).
`session_terminal`	409
`report_not_ready`	409	The research turn has no delivered report yet — keep polling (this is the normal in-progress answer).
`session_run_in_flight`	409
`idempotency_key_reuse`	409
`session_limit_exceeded`	403
`missing_api_key`	401	No Authorization header. Send `Authorization: Bearer <key>`.
`invalid_api_key`	401	The key does not exist or is malformed.
`revoked_api_key`	401	The key was revoked; create a new one in the console.
`expired_api_key`	401	The key passed its expiry; create a new one in the console.
`key_prefix_retired`	401
`insufficient_scope`	403	The key lacks the scope this endpoint needs.
`tier_restricted`	403
`plan_requires_payment_method`	403
`session_auth_required`	403
`topups_disabled`	400
`admin_required`	403	Signed in, but this area needs an administrator account.
`not_found`	404	The site demo endpoint is not enabled; use the public search endpoint with an API key.
`origin_not_allowed`	403	The demo endpoint only serves the product site; use the public search endpoint with an API key.
`demo_rate_limited`	429	Too many demo searches from this address; wait a minute or sign up for an API key.
`model_override_not_allowed`	403	The model-override query parameter is only available to designated benchmark organizations; remove it.
`unknown_model`	400	The model-override query parameter names a deployment that is not registered; use a registered deployment name.
`corpus_not_enabled`	403
`account_suspended`	403
`forbidden`	403
`document_not_found`	404
`entity_not_found`	404
`key_not_found`	404
`key_not_revealable`	404
`unknown_endpoint`	404
`eval_not_found`	404
`quota_exhausted`	402	Credit wallet empty. Add credit in the console before retrying.
`spending_cap_reached`	402
`research_budget_exhausted`	402
`invoice_overdue`	402
`request_in_flight`	409
`request_too_large`	413	Body exceeds the contract limit.
`rate_limit_exceeded`	429	Wait for Retry-After, then retry with backoff if still rate-limited.
`shared_capacity_exceeded`	429
`concurrency_limit_exceeded`	429	Too many runs in flight for the org; finish or cancel one.
`daily_request_quota_exceeded`	429
`playground_corpus_budget_exhausted`	429
`edge_rate_limit`	429
`redistribution_restricted`	451
`internal_error`	500	Our bug. Retry once; if it persists, report the request_id.
`not_implemented`	501	The endpoint is parked; the message says what to use instead.
`upstream_unavailable`	503	Our upstream had a problem; retry with backoff (Retry-After is set). Never your fault.
`capacity_exceeded`	503
`metering_unavailable`	503
`session_store_unavailable`	503
`research_incomplete`	503
`upstream_timeout`	504	The upstream ran past its budget; retry with backoff.

Contact support ↗Back to Quickstart ↑