Errors & limits

Error format

Errors use standard HTTP status codes and come back in the same envelope as successful responses, with data set to null:

{
  "requestId": "bb01c5ed-…",
  "data": null,
  "error": {
    "message": "Invalid API key provided",
    "code": "invalid_api_key"
  }
}

Validation errors also include details, listing the fields at fault. Include the requestId when you contact support.

Status codes

Status	code	What to do
401	missing_api_key, invalid_api_key, api_key_revoked	Check the Authorization: Bearer … header and the key.
402	insufficient_balance	Top up credits in the platform.
403	permission_denied	Your organisation can't use this feature. Contact support.
404	audience_not_found	Check the audienceId.
409	stale_audience	The saved audience's Twins are no longer available. Recreate it.
422	validation	The request body is invalid. See details.
422	insufficient_twins	Too few Twins match the audience. See Not enough Twins.
422	policy_violation	A question breaks the content policy. Rephrase it.
422	unsupported_country	The audience is in a country we don't cover yet.
422	divergent_audience	The audience description couldn't be read as one audience. Split it into separate asks.
500, 503	internal_server_error, service_unavailable	Retry with backoff. If it persists, contact support.

Timeouts

An ask takes tens of seconds. Described audiences take longest because matching Twins are found first. Give your HTTP client a timeout of a few minutes.

Billing

You pay per answer: participants returned × questions. A 5-question ask to 25 participants is 125 answers. Check your balance in the platform.

Volume

If you plan to run many asks in parallel or need high daily volume, talk to us first: support@originalvoices.ai.