Error codes — the hm_* taxonomy with remediation
Every error the Hotelminder API returns carries a stable string code under the hm_* prefix. This is the table your integration should switch on, and what to do when each one lands.
Errors from the Hotelminder API always carry a stable string code as their canonical identifier. The HTTP status is informational; your integration should switch on the string code, because we may occasionally add finer-grained codes without changing the status.
Response shape
{
"error": "hm_409_module_already_active",
"message": "Rate Reasoner is already active on this property; use PATCH to change tier.",
"documentation": "https://mindermod.org/docs/error-codes#hm_409_module_already_active",
"request_id": "hm_req_01H9K...",
"details": {
"property_id": "hm_p_01H9K...",
"module_id": "rate-reasoner"
}
}The request_id is the identifier your advisor will ask for if you contact support. Log it on every error.
Authentication and authorization
| Code | Status | Remediation |
|---|---|---|
hm_401_missing_scope | 401 | Your access token is valid but missing the required scope for the endpoint. Re-issue the token with the correct scope; see the API reference for the scope table. |
hm_401_token_expired | 401 | Access token has expired. Refresh using the refresh token from the OAuth2 flow. |
hm_401_signature_mismatch | 401 | Webhook signature did not verify. Check you are signing raw request bytes, not a re-serialised body. |
hm_403_property_scope_mismatch | 403 | Token is scoped to a different property than the one addressed. Regenerate the token with the correct property scope. |
hm_403_pilot_pack_scope | 403 | The action requires a paid subscription; the module is currently on a pilot pack. Convert the pilot pack via the dashboard or contact your advisor. |
Conflict — 409
| Code | Status | Remediation |
|---|---|---|
hm_409_module_already_active | 409 | The module is already active on this property. Use PATCH to change the tier or POST to /pause first if you intend to reset. |
hm_409_pilot_pack_active | 409 | A pilot pack is already running for this module. Extend or convert it via the pilot-packs endpoints. |
hm_409_advisor_scope_locked | 409 | Another advisor holds an open scoping session for this property. Wait for their scoping to close or coordinate handover. |
Validation — 422
| Code | Status | Remediation |
|---|---|---|
hm_422_boutique_size_exceeded | 422 | The property's declared room count exceeds the boutique guardrail (80 rooms). Contact your Hotelminder advisor — the platform is not sized for chain-scale operations and the wrong stack is being asked to serve it. |
hm_422_invalid_property_id | 422 | The property_id does not exist or is not accessible under the token's scope. |
hm_422_incompatible_tier | 422 | Requested tier is not compatible with the property's SiteMinder plan. See the compatibility notes on the module page in the catalog. |
hm_422_missing_siteminder_connection | 422 | No live SiteMinder connection on this property. Complete the handshake per the connection guide before activating any module. |
hm_422_country_not_supported | 422 | Country requested on a Fiscal Composer activation is not yet supported. See the current country list in the catalog. |
Rate limits and server errors
| Code | Status | Remediation |
|---|---|---|
hm_429_rate_limit_exceeded | 429 | Back off for the number of seconds in Retry-After. Do not tighten your polling loop; consider switching to webhook-driven updates. |
hm_500_internal | 500 | Unexpected internal error. Retry with exponential backoff. The request_id has been paged to on-call automatically if the issue persists. |
hm_503_siteminder_upstream | 503 | SiteMinder's upstream API is temporarily unreachable. The Hotelminder platform is healthy; wait and retry. Advisor tooling paints a yellow badge until the upstream recovers. |
On the boutique guardrail.
hm_422_boutique_size_exceeded is an intentional limit. Hotelminder curates for hotels of 10 to 80 rooms and the modules on the shortlist are tuned for that shape. If your property is larger, we would rather have an honest conversation than degrade the module's usefulness by stretching it.