Getting started
Errors & rate limits
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
Status codes
| Code | Name | Meaning | What to do |
|---|---|---|---|
200 |
OK | Success (search, health). | |
202 |
Accepted | Indexing queued, not yet applied. | Treat as success; confirm later with health or the sync history. |
401 |
Unauthorized | Bad or missing credentials, or an unknown site id. | Check the key and secret; ask the user to enter them again. |
402 |
Payment Required | The account has no active plan (reason: no_active_plan), or its plan is suspended for an overdue payment (reason: payment_overdue). |
Stop syncing; link the owner to plan.upgrade_url, or to Billing for payment_overdue. |
403 |
Forbidden | Site disabled, Origin not the site's own domain (search), or the account is suspended (reason: account_suspended). |
Enable the site again, search from the site's own domain, or contact support. |
404 |
Not Found | Unknown route. | Check the path. |
422 |
Unprocessable | Validation failed. | Inspect errors and fix the payload. |
429 |
Too Many Requests | Plan limit or rate limit reached. | Back off or upgrade the plan (see below). |
5xx |
Server error | Unexpected. | Retry with backoff and degrade gracefully. |
Error body shapes
Messages are written in German or English. Send an Accept-Language header
with your admin screen's language (de-DE, en-US) to get them in that
language; without it, they are German. The keys of errors, reason and the
status codes never change with the language, so match on those, not on the
text.
Validation (422)
Validation errors name each failing field:
{
"message": "The documents.0.type field is required.",
"errors": {
"documents.0.type": ["The documents.0.type field is required."]
}
}PUT /search-config also returns error_codes: for each key in errors, one
entry per message, in the same order, naming what went wrong in words that
never change with the language, and the limits it broke. Word your own
messages from these, and treat the translated errors as the fallback.
{
"message": "The Strength field must be between 1 and 50.",
"errors": {
"profit_ranking.strength": ["The Strength field must be between 1 and 50."]
},
"error_codes": {
"profit_ranking.strength": [{ "code": "out_of_range", "min": 1, "max": 50 }]
}
}code |
Meaning |
|---|---|
required |
A value is missing. |
not_a_number, not_a_boolean, not_a_string, not_a_list |
The value has the wrong type. |
out_of_range |
A number outside min and max. |
too_small, too_large |
Below min, or above max (a number, a text length or a list length). |
invalid_format |
The text does not have the format the field takes. |
not_allowed |
The value is not one the field accepts. |
limit_exceeded |
A plan limit, named in max. |
feature_unavailable |
The plan does not include the feature. |
invalid |
Any other reason. |
The messages are in the language of the Accept-Language header, German when
the request sends none.
Plan limit (429)
When a plan limit is reached, the body names the metric and the limit:
{ "metric": "documents", "limit": 50000 }metric is one of documents, searches and sites. A plan limit is not
a transient condition, so retrying will not help: the user has to remove data
or move to a larger plan.
Account not served (402/403)
Searching, indexing and MCP are refused for an account without an active plan
(cancelled, or a plan whose first payment is still open), for one whose plan
was suspended because a renewal stayed unpaid past the reminder's deadline,
and for a suspended account. The body carries a reason next to the
translated message. Branch on reason, never on the text:
{ "message": "This account has no active plan. …", "reason": "no_active_plan" }reason |
Status | What the owner does |
|---|---|---|
no_active_plan |
402 |
Chooses a plan (plan.upgrade_url). |
payment_overdue |
402 |
Pays the open invoice under Billing in the dashboard; service resumes as soon as the payment arrives. |
account_suspended |
403 |
Contacts support. |
This state is not transient either, so retrying will not help. /health,
/search-config, /upgrade-link and /disconnect keep answering, and
/health reports the same state in account.served and account.reason. A
caller without a valid key gets 401 and learns nothing about the account.
Auth / generic (401/403)
{ "message": "Invalid credentials." }An id that belongs to no site returns this same
401, not a404. The two cases are deliberately indistinguishable, so an unauthenticated caller cannot find out which site ids exist.
Rate limiting
All /api/v1 endpoints share a throttle per client:
| Limit | Window |
|---|---|
| 300 requests | per minute |
The AI features spend the site's monthly AI allowance with a key that is public in its pages, so they have tighter limits of their own:
| Endpoint | Per address | Per site, from every address |
|---|---|---|
POST /assistant, POST /assistant/stream |
15 a minute, 120 an hour | 60 a minute |
POST /search/visual |
10 a minute, 40 an hour | 20 a minute |
When a limit is exceeded, you receive 429 with the standard headers:
| Header | Meaning |
|---|---|
Retry-After |
Seconds to wait before retrying. |
X-RateLimit-Limit |
The cap (300). |
X-RateLimit-Remaining |
Requests left in the window. |
Two different
429s. A rate limit429carriesRetry-Afterand is transient: back off and retry. A plan limit429carries{ metric, limit }and is not transient. Branch on the body.
Connect-specific responses
POST /connect (see Building a plugin)
has its own limits and error codes, separate from the general API above:
| Code | Meaning | What to do |
|---|---|---|
409 |
The site_url is already connected (to a different idempotency_key). |
Do not retry with a new key. The owner recovers access through the dashboard, not through this endpoint. |
422 |
Validation failed, including a consent checkbox that was not accepted. | Fix the payload; both consents.terms_privacy and consents.dpa must be true. |
429 |
Rate limit reached: 20 per hour per IP, 5 per day per domain, 5 per day per recipient email (tighter than the general 300 per minute). | Back off; this is not a plan limit. |
503 |
The service cannot create accounts at the moment. | Retry later; your plugin cannot fix this. |
A 201 with {"status": "pending_claim"} is not an error. It means the
email matched an existing account and the owner has to finish connecting
through an emailed link. Show the owner a "check your email" message rather
than treating it as a failure.
Recommended client behaviour
flowchart TD
R["Send request"] --> S{Status}
S -- 2xx --> OK["Done"]
S -- "429 + Retry-After" --> W["Wait Retry-After, retry (cap attempts)"]
W --> R
S -- "429 + metric/limit" --> P["Stop. Surface 'limit reached' to user"]
S -- "402/403 + reason" --> N["Stop. Surface 'no active plan' / 'suspended'"]
S -- 401/403 --> A["Surface credential/domain error"]
S -- 422 --> V["Fix payload from errors{}"]
S -- 5xx --> B["Exponential backoff, then fall back to native search"]
B --> RPractical rules for a plugin:
- Retry only on
429withRetry-After, and on5xx, with exponential backoff and a small cap on attempts. - Never retry
422,401,402or403. Fix the cause instead. - Recognise a plan limit
429(metricpresent) and show an actionable message ("You've reached your document limit. Upgrade your plan to index more."). - Throttle yourself below 300 requests per minute when syncing in bulk: batch documents and pace requests.
- Always degrade gracefully in search: a failed call should fall back to the platform's built-in search, never to a broken results page.