Errors and rate limits

Use HTTP statuses and error codes to recover from failed requests.

REST resource errors include an HTTP status and JSON body. MCP tool failures reuse code and message inside the tool result.

Error format

Check the HTTP status, then code. Show or log message, but avoid matching its wording. Validation failures may include errors with a path identifying each rejected field.

400 invalid_request

{
  "message": "Invalid request",
  "code": "invalid_request",
  "errors": [
    {
      "path": "startDate",
      "message": "Use YYYY-MM-DD",
      "code": "invalid_date"
    }
  ]
}

Parameter codes in errors[].code include the following; body validation also returns schema codes: invalid_date, future_date, invalid_range, range_too_long, too_much_data, unknown_engine, invalid_country, invalid_dimension, query_needs_page, invalid_limit, invalid_offset, invalid_cursor, invalid_uuid, invalid_status, invalid_kind, invalid_source, invalid_boolean, required and invalid.

HTTP statuses and error codes

Status	Code	Cause
`400`	`invalid_request`	An input failed validation. Field details may appear in `errors`.
`400`	`engine_not_in_plan`	A requested engine is unavailable to the account. Remove it from `engines`.
`401`	`unauthorized`	Authentication failed because the token is absent, unrecognized or revoked.
`403`	`forbidden`	Account access or token permissions do not allow this request. Check the message for the cause.
`404`	`not_found`	The resource is missing or unavailable to this account, including inactive brands.
`409`	`conflict`	The fix action is invalid for its current state, or another update changed it concurrently.
`409`	`limit_reached`	The account’s active-question capacity is exhausted.
`429`	`rate_limited`	A quota was reached or could not be checked. Wait the `Retry-After` delay before retrying.
`500`	`server_error`	The server failed to complete the operation.

403 forbidden indicates account suspension, missing account access or insufficient token scope. Read message to distinguish the cause.

Rate limits

REST and MCP share account limits of 1,000 requests per rolling hour and 100,000 per rolling 30 days. These headers appear after access and scope checks pass. On allowed requests, they describe the hourly quota:

X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

An exhausted quota returns 429 rate_limited and a Retry-After delay in seconds. Quota headers describe the blocked window. Quota-storage failures also reject requests. The reset header uses Unix seconds.

When to retry

Correct the input before retrying 400.
For 401 or 403, resolve the token, scope or account-access problem first.
For 409, free question capacity after limit_reached. After conflict, read the fix again; its state may have changed concurrently.
Wait the full Retry-After interval before retrying 429.
Use bounded backoff with jitter for 500. Fix actions and question archiving tolerate repeats. A failed question batch may have created some items; check first.

Versions and route retirement

Allow unknown fields when reading v1 responses. The older routes listed below still respond with Deprecation: true, a Sunset date and a Link to the API reference for replacement guidance.

The announced sunset is 26 December 2026 for /brands/{brandId}/visibility, /mentions, /citations, /sentiment, /pages and PATCH /fixes. These routes accept the same tokens. Migrate to the brand report, answers, the URL report and the fix actions.

Contact support

Include the endpoint, request time, HTTP status and error code when contacting support@searchseal.com. Leave tokens out of the message.

Try the quickstart or browse the API reference.