Error Codes — Suite Profit

4xx — authentication and authorization

Code	HTTP	Meaning	Remediation
SP-AUTH-INVALID-TOKEN	401	Bearer token missing, malformed, or revoked	Re-issue the OAuth client credentials token; rotate through the Suite Profit admin console.
SP-AUTH-EXPIRED-SAML	401	SAML assertion expired on a user-scoped endpoint	Re-authenticate through the identity provider; re-federate against Okta / Entra ID / PingFederate.
SP-AUTH-INSUFFICIENT-ROLE	403	Principal lacks the role required for this portfolio or property	Grant the missing role through SCIM or the admin console; roles are portfolio-scoped.
SP-RATELIMIT-EXCEEDED	429	Per-portfolio rate limit exceeded	Honour `Retry-After` and back off. See rate limits.

4xx — Profitroom integration

Code	HTTP	Meaning	Remediation
SP-PR-API-MISMATCH	422	Profitroom Suite API version mismatch or schema drift on the property	Re-run the Profitroom compatibility probe from the admin console; re-register the property token.
SP-PR-DEPENDENCY-FAIL	424	A dependency on the Profitroom side failed — Booking Engine unavailable, Rate Manager frozen	Retry once Profitroom Suite recovers. Queued writes replay automatically.

4xx — business state

Code	HTTP	Meaning	Remediation
SP-DECISION-CONFLICT	409	Conflicting rate decision on the same property/room/date range	GET the current decision, reconcile, resubmit with the latest `version`.
SP-PROPERTY-FROZEN	409	Property is temporarily frozen — governance freeze or fiscal batch in flight	Wait for the freeze to lift; check `/portfolios/{id}/properties` for status.
SP-ENTITY-DISABLED	410	The addressed entity was disabled by an operator	Re-enable through the admin console or contact the portfolio administrator.

5xx — Suite Profit and upstream

Code	HTTP	Meaning	Remediation
SP-INTERNAL	500	Internal Suite Profit error	Retry with exponential backoff. Persistent occurrences are covered by the Enterprise SLA credit rule below.
SP-PR-UPSTREAM	502	Profitroom Suite upstream returned a non-recoverable error	Wait for recovery. Queued writes replay automatically once Profitroom is healthy.
SP-CIRCUIT-OPEN	503	Circuit breaker open on the affected module — protecting the portfolio from cascading upstream failure	Wait for the half-open probe; state transitions are on the status page and mirrored to the audit stream.
SP-PR-TIMEOUT	504	Profitroom Suite timed out on the write path	Retry with an `Idempotency-Key`; queued writes replay automatically.

Error body examples

An authorization failure (SP-AUTH-INSUFFICIENT-ROLE) carries the missing role and the portfolio it was evaluated against:

{
  "error": "insufficient_role",
  "code": "SP-AUTH-INSUFFICIENT-ROLE",
  "message": "Principal lacks role portfolio.rate.publish",
  "details": {
    "portfolio_id": "prt_motlawa_estates",
    "required_role": "portfolio.rate.publish",
    "granted_roles": ["portfolio.rate.read", "portfolio.reputation.read"]
  }
}

A Profitroom dependency failure (SP-PR-DEPENDENCY-FAIL) surfaces the upstream sub-code:

{
  "error": "profitroom_dependency_failed",
  "code": "SP-PR-DEPENDENCY-FAIL",
  "message": "Profitroom Rate Manager unavailable for property",
  "details": {
    "property_id": "prop_gdansk_marina",
    "profitroom_status": 503,
    "profitroom_reason": "rate_manager_maintenance"
  }
}

SLA credit on 5xx availability breach

Enterprise plans carry a 99.95% monthly availability SLA on the v2 API. Every 0.1% breach below the SLA earns a 5% credit on the monthly Enterprise fee, capped at 30% per calendar month. Availability is measured on 5xx codes attributable to Suite Profit (SP-INTERNAL, SP-CIRCUIT-OPEN); SP-PR-UPSTREAM and SP-PR-TIMEOUT breaches are surfaced separately and covered by the Profitroom dependency clause of the master agreement. Every incident is written to the audit stream so verification does not require a support ticket.

Which errors are safe to retry

Retry-safe (idempotent, transient): SP-RATELIMIT-EXCEEDED, SP-INTERNAL, SP-PR-UPSTREAM, SP-CIRCUIT-OPEN, SP-PR-TIMEOUT. Retry after resolving state: SP-DECISION-CONFLICT, SP-PROPERTY-FROZEN. Never retry as-is: SP-AUTH-INVALID-TOKEN, SP-AUTH-EXPIRED-SAML, SP-AUTH-INSUFFICIENT-ROLE, SP-PR-API-MISMATCH, SP-ENTITY-DISABLED — these require correcting the request, the identity, or the surrounding state first.

When to page the account team

If you see sustained SP-INTERNAL or SP-CIRCUIT-OPEN for more than 10 minutes and the status page is green, page your named account manager or email noc@suiteprofit.org. Enterprise plans have a 15-minute NOC response SLA during CET business hours and a 60-minute out-of-hours SLA.