Orvelt

Errors

What each Business API status means, how to recover, and how to stay under the rate limit.

Failed requests return an HTTP status and a JSON body. Find the status below, apply the fix, and only then retry.

Error body

Every error body has the same top-level fields.

Fields

{
  "code": "LINK_EMAIL_COOLDOWN",
  "status": 429,
  "message": "A delivery link was already emailed to this customer recently.",
  "data": { "nextEligibleAt": "2026-10-11T09:30:00.000Z" }
}
  • code is a stable identifier. Branch on it, not on message.
  • message is a human-readable explanation. Its wording can change.
  • data appears only on codes that carry extra detail, listed below.

Statuses and fixes

Retry 429 and 503 with backoff. For every other status, change the request first: sending it again unchanged returns the same error.

Status table

StatusCodeCauseWhat to do
400BAD_REQUESTA field is missing, out of range, or the wrong type.Fix the request. See the checks below.
401UNAUTHORIZEDThe key is missing, mistyped, expired, or revoked.See the checks below.
403FORBIDDENThe key lacks the operation's permission, or the project belongs to another organization.See the checks below.
403PLAN_LIMIT_REACHEDThe action would exceed the organization's plan.Read data.metric, data.currentUsage, and data.limit, then upgrade under Billing or wait for the next period.
404NOT_FOUNDThe project or resource in the path does not exist.Copy the IDs again from Orvelt Business. Do not retry.
409CONFLICTThe resource changed or can no longer be used, such as an expired delivery link.Fetch the resource again, or create a new one, then retry.
429TOO_MANY_REQUESTSThe key used up its hourly request limit.Wait, then retry with backoff.
429LINK_EMAIL_COOLDOWNThis customer already received a delivery-link email from this project in the last 48 hours.Do not retry before data.nextEligibleAt.
503SERVICE_UNAVAILABLEA dependency is temporarily unavailable, or a new project is still being set up.Retry with exponential backoff.

401 checks

  1. Check that the environment variable holds the complete key, starting with ov_.
  2. Check the header name is exactly x-api-key.
  3. Open Manage Settings → API Keys and confirm the key has not expired or been revoked. Create a new key if it has.

403 checks

  1. Confirm your key includes the operation's permission. Older keys do not gain new question or invitation grants automatically.
  2. Confirm the project ID in the path belongs to the key's organization.
  3. For a session-only operation, use a Business session with the required member access instead of an API key.

400 checks

Compare your request with the operation's reference entry. Common causes:

  • A required question field is missing, or answers.options has fewer than 2 entries for a select question.
  • An enum value is misspelled, such as mostUpvoted instead of most-upvoted.
  • dateFrom is later than dateTo.

Empty lists

An empty list is a successful response: the project has no matching rows, or your filters exclude all of them. Drop optional filters, request page=1, and confirm the project ID before you contact support.

Rate limits

Each API key can send up to 1000 requests per hour. Every job that shares a key shares that budget, including scheduled syncs and exports. Over the limit, requests return 429 TOO_MANY_REQUESTS until the key's one-hour window resets.

Retry with backoff

Wait longer after each failed attempt, add random jitter, and stop after a fixed number of attempts. The TypeScript SDK and Python SDK document their retry behavior.

429 LINK_EMAIL_COOLDOWN is different: it applies to one customer, not your key. Do not retry it on a timer; wait until data.nextEligibleAt.

Send fewer requests

  • Use limit=100 for bulk reads instead of many small pages.
  • Save the last page or date range a sync finished, and start there next time.
  • Subscribe to webhooks instead of polling for new opinions.
  • Give separate jobs separate keys so one busy job cannot exhaust another's budget.