Errors and rate limits

Every SEOFix API error has the same shape: {"error": {"code": "...", "message": "..."}} with a matching HTTP status. Branch on code, not on message. Each API key may make 60 requests per minute; some endpoints have an extra, lower limit. Retry only 429, 503 and report_not_ready, and honour Retry-After.

#The error envelope

{
  "error": {
    "code": "site_not_verified",
    "message": "Rechecks need a verified site. Verify ownership first: see GET /v1/sites/{id}/verification."
  }
}

• code is stable and machine-readable. message is for people and can change.
• Validation errors add fields, the failing parameters with their messages:

{
  "error": {
    "code": "validation_failed",
    "message": "The max rps field must not be greater than 10.",
    "fields": {"max_rps": ["The max rps field must not be greater than 10."]}
  }
}

• budget_exhausted adds resets_at (ISO 8601).
• Unexpected server errors answer 500 internal_error and never include internal details.

Over MCP, a failed tool returns the same code as text: code: message, with isError: true.

#Error codes

#Any endpoint

#Credits and plans

#Audits

#Sites

#Fix tasks and rechecks

#Google Search Console

#IndexNow

#Billing

#Device login (npx seofix connect)

#MCP-only codes

The MCP server adds three codes of its own:

#Rate limits

The per-endpoint limits apply in addition to the 60 per minute. All keys of one user count separately; the recheck limit is shared by everyone in the team.

Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. A 429 rate_limited answer also carries Retry-After (seconds). recheck_rate_limited and budget_exhausted carry Retry-After too.

#Insufficient credits

Audits and rechecks reserve credits before they start:

• An audit reserves its full page cap (max_pages). The unused part is refunded when it ends.
• A recheck reserves 1 credit per URL.

If the balance that pays for it is lower, the API answers 402 insufficient_credits and creates nothing: no audit, no reservation. A recheck refused this way does not count against the hourly recheck limit.

Which balance pays: a plain-URL audit (POST /v1/crawls with url) uses the key holder's own balance; audits of a registered site, scheduled audits and rechecks use the team owner's balance. GET /v1/account shows both (balance and team_credits).

To proceed: lower max_pages to fit the balance, or add credits (Settings → Plan & billing in the app, or a checkout link from POST /v1/billing/checkout for the team owner). Do not retry the same request unchanged.

#Retry guidance

Never retry POST /v1/crawls or POST /v1/sites/{id}/recheck after a timeout without checking first: the audit or recheck may have started. List audits with GET /v1/crawls?site_id= before starting another. Over MCP, verify_fix never starts a second recheck on its own; continue with get_recheck.

#Related

• API reference
• REST API quickstart
• Agent playbook
• Plans and credits