Errors | aVenture Developer Docs

Every failed API, CLI, or MCP call returns one body: an RFC 9457 problem detail, served as application/problem+json. Parse that one shape to handle every failure.

The Problem Detail Body

type, title, status, detail, and instance are the RFC standard fields. The remaining fields are aVenture extensions, present only when they apply:

code is a machine-readable secondary code for when the status alone does not identify the recovery path. Branch on code, not on detail, because detail is prose and can be reworded.
hint, suggestion, and resolution say how to correct the request. resolution can name the endpoint that clears the problem.
field, value, unknownParameters, and validParameters identify the rejected part of the request on a validation failure.
details carries structured conflict information on a 409, including the candidates from an ambiguous lookup. Select the intended record by its returned id.
limitType, limit, used, remaining, resetAt, and retryAfterSeconds describe the limit that refused a 429.
traceId and spanId identify the request. Quote them when you contact support.

Status Codes

Status	Meaning	What to do
`400`	Malformed request or invalid parameter	Read `field` and `hint`, fix the request, and resend
`401`	Missing or unrecognized credential	Sign in or send an API key; create an account if you don’t have one
`402`	Your plan does not include the operation, or your subscription is canceled, past due, or paused	Read `code`, then fix the subscription as described in subscription refusals
`403`	Valid bearer token that lacks permission for this operation	Check the permission the operation requires
`404`	No record matches	Resolve the record by name or URL before reading it
`406`	The requested content type cannot be served	Send `Accept: application/json`
`409`	Conflict with an existing record, or a lookup that matched more than one record	Choose from `details.candidate` when present; otherwise list records by name
`415`	Unsupported request content type	Send `Content-Type: application/json`
`422`	Well-formed but semantically rejected	Read `detail` and `resolution`
`429`	You reached your plan’s usage limit, or sent requests too fast	Read `code`, then follow usage limits or rate limits
`500`, `503`	Server error or unavailable dependency	Retry with backoff; `503` is usually transient. A `503` with `code` `search_still_running` means the search is still running; retry after `Retry-After`, or send `Prefer: respond-async` to get a job to poll

Retry 500, 503, and a 429 from a request-rate limit. Do not retry 400, 401, 402, 403, 404, 406, 409, 415, or 422, because the same request fails the same way.

Subscription Refusals

A 402 means the operation needs a subscription state your account does not have. code names the cause:

`code`	Cause	Fix
`subscription_required`	Your plan does not include this feature	Choose a plan that includes it on the pricing page
`subscription_canceled`	The subscription was canceled	Subscribe again from the pricing page
`subscription_past_due`	A payment failed or is unfinished	Update the payment method from your subscription settings
`subscription_paused`	The subscription is paused	Resume it from your subscription settings

Plain-English search, link search, and research requests can answer 402. Plans and usage explains how plans gate features.

Rate Limits

A request-rate limit answers 429 and carries its state in the problem detail and in the Retry-After header:

{
  "title": "Too Many Requests",
  "status": 429,
  "code": "rateLimited",
  "limit": 100,
  "remaining": 0,
  "used": 100,
  "windowSeconds": 60,
  "resetAt": "2026-09-04T12:00:00Z",
  "retryAfterSeconds": 12,
  "limitType": "IP"
}

Wait retryAfterSeconds before retrying, and add random jitter so parallel workers do not resume at the same moment. resetAt gives the same deadline as an absolute timestamp.

limitType names the limit you hit. IP, SUBNET, and GLOBAL are request-rate limits. NATURAL_SEARCH, WEB_SEARCH, and INFERENCE_PROVIDER limit one feature, so other endpoints can still succeed.

Usage Limits

When you have used a monthly allowance, such as company profile views, person profile views, or web searches, the API answers 429 with code billing_allowance_exhausted:

{
  "title": "Usage limit reached",
  "status": 429,
  "code": "billing_allowance_exhausted",
  "detail": "Usage limit reached: your Essential plan includes 25 company profile views per month, and you have used them all.",
  "hint": "Upgrade now at https://aventure.vc/settings/subscription (plans: https://aventure.vc/pricing). In the aVenture CLI, the `billing plans list` command shows monthly and annual prices; in an MCP client, ask your assistant to upgrade. Otherwise the allowance refills at 2026-10-01T00:00Z.",
  "allowanceType": "ENTITY_VIEW",
  "limitType": "BILLING_ALLOWANCE",
  "limit": 25,
  "used": 25,
  "remaining": 0,
  "resetAt": "2026-10-01T00:00:00Z",
  "resolution": { "action": "useEndpoint", "endpoint": "/v1/billing/checkout-sessions" }
}

Stop sending that kind of request instead of retrying. Upgrade from subscription settings, from the CLI, or from your MCP client as described in When you reach a limit, or wait for resetAt. resolution.endpoint names the call that starts the upgrade: checkout for the free plan, a plan change for a paid one.

On plans with additional usage turned on, a 429 with code billing_additional_usage_cap_reached means you reached the spending cap you set or used your prepaid credit. Raise the cap in subscription settings to continue.

Redirects on Changed Slugs

GET /v1/entities/lookup-exact, GET /v1/people/lookup-exact, and GET /v1/news/lookup can answer 301 instead of 404 when a record’s slug has changed. Follow the redirect, which curl -L and most HTTP clients do by default, and store the slug you land on.