Error Format
Understand an API error message and decide what to check next.
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.
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
- Read the response's code and message.
- Check any fields named in the error and correct the request.
- If the result of a change is unclear, check the current state before trying again.
Theme color