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" }
}codeis a stable identifier. Branch on it, not onmessage.messageis a human-readable explanation. Its wording can change.dataappears 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
| Status | Code | Cause | What to do |
|---|---|---|---|
400 | BAD_REQUEST | A field is missing, out of range, or the wrong type. | Fix the request. See the checks below. |
401 | UNAUTHORIZED | The key is missing, mistyped, expired, or revoked. | See the checks below. |
403 | FORBIDDEN | The key lacks the operation's permission, or the project belongs to another organization. | See the checks below. |
403 | PLAN_LIMIT_REACHED | The 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. |
404 | NOT_FOUND | The project or resource in the path does not exist. | Copy the IDs again from Orvelt Business. Do not retry. |
409 | CONFLICT | The 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. |
429 | TOO_MANY_REQUESTS | The key used up its hourly request limit. | Wait, then retry with backoff. |
429 | LINK_EMAIL_COOLDOWN | This customer already received a delivery-link email from this project in the last 48 hours. | Do not retry before data.nextEligibleAt. |
503 | SERVICE_UNAVAILABLE | A dependency is temporarily unavailable, or a new project is still being set up. | Retry with exponential backoff. |
401 checks
- Check that the environment variable holds the complete key, starting with
ov_. - Check the header name is exactly
x-api-key. - Open Manage Settings → API Keys and confirm the key has not expired or been revoked. Create a new key if it has.
403 checks
- Confirm your key includes the operation's permission. Older keys do not gain new question or invitation grants automatically.
- Confirm the project ID in the path belongs to the key's organization.
- 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.optionshas fewer than 2 entries for a select question. - An enum value is misspelled, such as
mostUpvotedinstead ofmost-upvoted. dateFromis later thandateTo.
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=100for 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.