Error Format
Error Format explains how SHM reports failed API requests and what integrations should do with each class of error.
Where to find it: Documentation > Hosting Manager > API > Error Format.
Available to: Anyone reading the public documentation. The related SHM action still follows the role stated on its page.
What this page does
Error Format explains how SHM reports failed API requests and what integrations should do with each class of error.
Before you start
Examples use placeholder accounts, domains, addresses, and credentials. Replace them deliberately, and never paste passwords, API keys, tokens, or private keys into tickets or shared notes.
Why use it — and when not to
Use Error Format to understand or plan the supported workflow. Do not treat an example as authorization or as proof of the current state on a particular SHM server.
Standard error shape
{
"status": "error",
"code": "validation_error",
"message": "One or more required parameters are missing or invalid.",
"request_id": "req_example",
"errors": {
"domain": "The domain field is required."
}
}Common error classes
| Code | Meaning | Recommended client behavior |
|---|---|---|
| authentication_required | Missing X-Api-User or X-Api-Key headers. | Do not retry blindly. Fix authentication headers and key loading first. |
| access_denied | The key is valid but not allowed for the endpoint, account, object, role, or source IP. | Stop the operation and use the correct role/scope or ask an administrator to delegate access. |
| validation_error | One or more required or typed parameters are missing or invalid. | Show the validation message to the operator and correct the request body, query, or path values. |
| not_found | The target account, domain, id, job, certificate, database, file, or service object was not found in the permitted scope. | Refresh list/context data before retrying. |
| conflict | The request conflicts with current state, such as duplicate resource, account already suspended, running job, or object still in use. | Read current state and decide whether the action is already complete or needs a different target. |
| operation_failed | The backend service could not complete the task after validation succeeded. | Check SHM logs, related service status, and job/progress output before retrying. |
Error handling best practices
- Display the message field to operators, but never display secrets or raw credentials.
- Use request_id or correlation values when contacting support so logs can be matched quickly.
- Treat access_denied as a configuration or permission issue, not a transient failure.
- Retry GET requests with backoff when network or temporary service errors occur.
- Do not retry destructive requests unless the previous result is unknown and the endpoint is safe to repeat.
How to use it
- Identify whether the task is server-wide, reseller-scoped, or limited to one account.
- Open the page that owns the resource instead of using a nearby page with a similar name.
- Read the page-specific prerequisites and impact before changing anything.
- Verify the result in SHM and from the customer-facing service.
Result and next check
Reading this page changes nothing in SHM. Follow the linked workflow only after confirming the role, target, and expected impact.
Theme color