Error Codes Quick Reference
FreshHTTP Status Codes
| Code | Name | Meaning |
|---|---|---|
| 200 | OK | Success |
| 201 | Created | Resource created |
| 204 | No Content | Deleted successfully |
| 400 | Bad Request | Invalid input |
| 401 | Unauthorized | Auth failed |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 405 | Method Not Allowed | Wrong HTTP method |
| 409 | Conflict | Duplicate resource |
| 422 | Unprocessable | Validation failed |
| 429 | Too Many Requests | Rate limited |
| 500 | Server Error | PHP/server issue |
| 502 | Bad Gateway | Proxy error |
| 503 | Unavailable | Overloaded/maintenance |
| 504 | Timeout | Request too slow |
REST API v2 Error Codes
| Code | Cause | Fix |
|---|---|---|
mainwp_rest_invalid_api_key | Bad API key | Regenerate key |
mainwp_rest_forbidden | Lacking permissions | Use admin account |
mainwp_rest_site_not_found | Invalid site_id | Check site list |
mainwp_rest_site_disconnected | Site offline | Reconnect site |
mainwp_rest_child_error | Child site error | Check child logs |
mainwp_rest_timeout | Connection timeout | Increase timeout |
mainwp_rest_invalid_param | Bad parameter | Check param types |
Abilities API Error Codes
| Code | HTTP | Cause | Fix |
|---|---|---|---|
ability_not_found | 404 | Bad ability slug | Check slug name |
invalid_input | 400 | Validation failed | Check parameter format |
missing_required_input | 400 | Missing param | Add required parameter |
unauthorized | 401 | Not authenticated | Check credentials |
forbidden | 403 | No permission | Use admin account |
confirmation_required | 400 | Destructive action | Re-submit with confirm token |
confirmation_expired | 400 | Token >5 min old | Request new preview |
safe_mode_blocked | 403 | Safe mode on | Disable MAINWP_SAFE_MODE |
rate_limited | 429 | Too many requests | Wait and retry |
batch_queued | 202 | >200 sites | Poll with job_id |
MCP Server Errors
| Error | Cause | Fix |
|---|---|---|
ECONNREFUSED | Can't reach server | Check URL/firewall |
401 | Bad credentials | Check user + app password |
403 | No permission | Need admin role |
SSL_ERROR | Cert issue | Fix cert or skip verify |
TIMEOUT | Too slow | Increase MAINWP_REQUEST_TIMEOUT |
WordPress Application Password Errors
| Error | Cause | Fix |
|---|---|---|
| "Application passwords not available" | Disabled in WP | Enable in wp-config or remove blocking plugin |
| "Invalid username or password" | Wrong credentials | Verify username + regenerate password |
| "The requested user does not exist" | Bad username | Check spelling, case sensitivity |
Connection Error Codes
| Error | Cause | Fix |
|---|---|---|
CHILD_NOT_FOUND | No child plugin | Install + activate MainWP Child |
SECURITY_ID_MISMATCH | IDs don't match | Reset on both sides |
OPENSSL_ERROR | Encryption failure | Reconnect (rotates keys) |
SITE_ALREADY_CONNECTED | Duplicate | Site already in Dashboard |
INSUFFICIENT_PERMISSIONS | Not admin | Use admin-level account |
Batch Job Status Codes
| Status | Meaning | Action |
|---|---|---|
queued | Waiting to start | Poll again in 30s |
processing | In progress | Poll again in 30s |
completed | All done | Read results |
failed | All operations failed | Check error details |
Rate Limit Headers
| Header | Description |
|---|---|
X-RateLimit-Limit | Max requests per window |
X-RateLimit-Remaining | Requests left |
X-RateLimit-Reset | Unix timestamp when limit resets |
Retry-After | Seconds to wait before retrying |