Status Codes

Fresh

Reference for HTTP and MainWP-specific error codes.

HTTP Status Codes

Success (2xx)

Code	Meaning	MainWP Context
200	OK	Request succeeded
201	Created	Resource created (site, client, tag)
204	No Content	Deletion succeeded

Client Errors (4xx)

Code	Meaning	MainWP Context
400	Bad Request	Invalid parameters, missing required fields
401	Unauthorized	Invalid API key, expired Application Password
403	Forbidden	User lacks required WordPress capability
404	Not Found	Resource doesn't exist (site_id, client_id, etc.)
405	Method Not Allowed	Wrong HTTP method (GET vs POST)
409	Conflict	Duplicate resource (site URL already exists)
422	Unprocessable Entity	Validation failed (invalid URL format, etc.)
429	Too Many Requests	Rate limit exceeded

Server Errors (5xx)

Code	Meaning	MainWP Context
500	Internal Server Error	PHP error, database issue
502	Bad Gateway	Reverse proxy can't reach PHP
503	Service Unavailable	Server overloaded or in maintenance
504	Gateway Timeout	Request took too long (increase timeouts)

MainWP-Specific Error Codes

REST API v2 Errors

Error Code	Description	Fix
mainwp_rest_invalid_api_key	API key missing or invalid	Generate new key in Dashboard → REST API Keys
mainwp_rest_forbidden	User cannot perform action	Check user capabilities
mainwp_rest_site_not_found	Site ID doesn't exist	Verify site_id with list endpoint
mainwp_rest_site_disconnected	Site not connected	Reconnect the site
mainwp_rest_child_error	Child site returned error	Check child site logs
mainwp_rest_timeout	Child site didn't respond	Increase timeout, check connectivity
mainwp_rest_invalid_param	Parameter validation failed	Check parameter types and formats

Abilities API Errors

Error Code	HTTP	Description
ability_not_found	404	Ability slug doesn't exist
invalid_input	400	Input validation failed
missing_required_input	400	Required parameter not provided
unauthorized	401	Not authenticated
forbidden	403	Lacks required capability
confirmation_required	400	Destructive action needs confirm token
confirmation_expired	400	Confirm token older than 5 minutes
safe_mode_blocked	403	MAINWP_SAFE_MODE is enabled
rate_limited	429	Too many requests per minute
batch_queued	202	Operation queued (>200 sites)

MCP Server Errors

Error	Cause	Fix
ECONNREFUSED	Can't reach Dashboard	Check URL, firewall, DNS
401 Unauthorized	Bad credentials	Verify username + Application Password
403 Forbidden	Missing capabilities	User needs admin role
SSL_ERROR	Certificate issue	Fix cert or set MAINWP_SKIP_SSL_VERIFY=true
TIMEOUT	Request too slow	Increase MAINWP_REQUEST_TIMEOUT

Abilities API Error Response Format

{
  "code": "invalid_input",
  "message": "The field 'site_id' is required.",
  "data": {
    "status": 400,
    "field": "site_id",
    "expected": "integer"
  }
}

Abilities API Annotations

Responses may include annotations providing additional context:

Annotation	Type	Description
info	Informational	Helpful context about the response
warning	Warning	Potential issue to be aware of
error	Error	Something went wrong for specific items
suggestion	Suggestion	Recommended next action

Example:

{
  "results": [...],
  "annotations": [
    {
      "type": "warning",
      "message": "3 sites were unreachable during this operation"
    },
    {
      "type": "suggestion",
      "message": "Run sync on unreachable sites before retrying"
    }
  ]
}

Rate Limiting

REST API v2

Setting	Default
Requests per minute	No hard limit (server-dependent)
Concurrent connections	Server-dependent

Abilities API

Setting	Default	Configurable
Requests per minute	60	MAINWP_RATE_LIMIT env var
Burst allowance	10	Not configurable

Rate Limit Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1234567890
Retry-After: 30