# Errors

URL: /docs/developers/errors

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

## Error body [#error-body]

Every error body has the same top-level fields.

### Fields [#fields]

```json
{
  "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 [#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-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](/docs/developers/authentication#included-permissions), 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 [#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 [#403-checks]

1. Confirm your key includes the operation's [permission](/docs/developers/authentication#included-permissions). 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](/docs/developers/authentication#session-only-operations), use a Business session with the required member access instead of an API key.

### `400` checks [#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 [#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 [#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 [#retry-with-backoff]

Wait longer after each failed attempt, add random jitter, and stop after a fixed number of attempts. The [TypeScript SDK](/docs/developers/typescript-sdk#retry-transient-failures) and [Python SDK](/docs/developers/python-sdk#retry-transient-failures) 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 [#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](/docs/developers/feedback/webhooks) instead of polling for new opinions.
- Give separate jobs separate keys so one busy job cannot exhaust another's budget.