Zum Inhalt springen

Getting started

Errors & rate limits

https://searcio.com/api/v1

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:

json
{
  "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.

json
{
  "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:

json
{ "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:

json
{ "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)

json
{ "message": "Invalid credentials." }

An id that belongs to no site returns this same 401, not a 404. 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 limit 429 carries Retry-After and is transient: back off and retry. A plan limit 429 carries { 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.

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 --> R

Practical rules for a plugin:

  1. Retry only on 429 with Retry-After, and on 5xx, with exponential backoff and a small cap on attempts.
  2. Never retry 422, 401, 402 or 403. Fix the cause instead.
  3. Recognise a plan limit 429 (metric present) and show an actionable message ("You've reached your document limit. Upgrade your plan to index more.").
  4. Throttle yourself below 300 requests per minute when syncing in bulk: batch documents and pace requests.
  5. Always degrade gracefully in search: a failed call should fall back to the platform's built-in search, never to a broken results page.