SearchStax Site Search API errors can include 429 Too Many Requests, 401 Unauthorized, and platform limit errors such as 413 and 414.
For example, a 429 error can appear like this:
Error: Request failed with status code 429429 Error Types and Messages
A 429 response doesn't always mean the same thing. It can indicate either temporary throttling or a plan-limit condition, so check the response body's message value first.
| Limit Exceeded | Response Code | Response Body |
|---|---|---|
| Max Requests per Second rate exceeded | 429 | {"message":"Too Many Requests"}
|
| Max Requests per Month exceeded | 429 | {"message":"Plan Limit Exceeded"}
|
| Max Doc Count Limit exceeded | 429 | {"message":"Plan Limit Exceeded"}
|
Use the response body to choose your next step:
-
{"message":"Too Many Requests"}means you hit a short-term request-rate limit. Wait a short time and retry. -
{"message":"Plan Limit Exceeded"}means you hit a plan limit. Check your monthly request and document limits to determine whether the issue is request volume or document count.
Response details: all three 429 cases use content-type: application/json and include these headers: access-control-allow-origin: *, access-control-allow-headers: *,Authorization, access-control-allow-methods: GET,OPTIONS, and access-control-expose-headers: *. 429 responses don't include a Retry-After header.
401 Unauthorized Errors
If you receive a 401 Unauthorized error with the message {"message":"Unauthorized"}, the issue is authentication-related, not rate limiting.
| Symptom | Response Code | Likely Cause |
|---|---|---|
| Write operation fails (update, delete, clear index) | 401 | Using a Read Only token instead of Read & Write token |
Solution: Verify you're using the correct token type. Write operations (adding, updating, or deleting documents) require Read & Write credentials. Find your tokens at Site Search > App Settings > All APIs > Search & Indexing. See Search & Indexing for details on token management.
Other Platform Limit Errors
In addition to 429 errors, you may encounter other HTTP error codes when exceeding platform limits:
| Limit Exceeded | Response Code | Response Body Message |
|---|---|---|
| Max Payload Size Limit exceeded (10MB) | 413 | HTTP content length exceeded 10485760 bytes
|
| Max Request Size Limit exceeded (10KB) | 414 | Request Entity Too Large
|
| Max URL Length Limit exceeded (10,240 characters) | 414 | Requests-URI Too Large
|
What Causes These Errors?
Rate Limit (Too Many Requests): Your application has sent too many queries and the server can't process them all. This typically occurs when your application exceeds 20+ API requests per second.
Monthly Request Limit: Your subscription's contracted number of monthly requests to the search service has been exceeded. SearchStax notifies you when approaching this limit.
Data or Document Count Limits: Your indexed data size or number of documents has exceeded your subscription plan limits.
Payload, Request, or URL Size Limits: Individual requests are too large. See the Service Limits article for specific size constraints.