Errors & Limits

This page documents API errors, rate limits, validation behavior, and operational limits.

Error format

PLACEHOLDER: Confirm the final error envelope. Current Laravel JSON errors may return:

{
  "message": "The q field is required.",
  "errors": {
    "q": [
      "The q field is required."
    ]
  }
}

Status codes

Status	Meaning	Typical cause
200	Success	Request completed.
401	Unauthenticated	Missing, invalid, or revoked API key.
404	Not found	Unknown endpoint or resource.
422	Validation failed	Invalid query parameter or invalid request body. (Imports over the store's product limit are not rejected — extra new products are skipped and reported in skipped_rows.)
429	Rate limited	Too many requests in the current window.
500	Server error	Unexpected application error.

Rate limits

Current autocomplete limit:

120 requests per minute

PLACEHOLDER: Confirm final limits per endpoint, plan, store, IP address, and API key.

Rate-limit headers

PLACEHOLDER: Confirm final headers. Expected headers may include:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119

Validation limits

Field	Limit
Products per free store	100
AI-enriched products per free store	5
Autocomplete query length	TODO
Autocomplete result limit	TODO
Product title length	TODO
Product URL length	TODO
Product image URL length	TODO
CSV file size	TODO

Retry guidance

• Do not retry 401 or 422 without changing the request.
• Back off when receiving 429.
• Retry transient 500 responses with exponential backoff.
• For browser widget requests, fail quietly so shoppers can continue using the storefront.