Errors and Limits
Guardhouse responses can be affected by endpoint validation, deployment safeguards, and plan-specific policies. Treat a limit as part of the public contract only when it is explicitly documented for your deployment or plan.
HTTP Status Codes
| Status | Meaning |
|---|---|
400 | Malformed input, validation failure, invalid OAuth request, or failed business precondition |
401 | Missing, expired, revoked, or otherwise invalid authentication |
403 | Authenticated caller lacks the required scope or policy |
404 | Requested user, role, permission, or relationship was not found |
409 | A unique key/name already exists or a relationship change conflicts with current state |
413 | Request payload exceeds the accepted size |
429 | Request was throttled by a service or deployment policy |
503 | Service is temporarily unavailable |
500 | Unexpected server failure |
Authentication middleware can return 401 or 403 before a System API handler runs. A valid token still needs the system_api scope.
Error Bodies
OAuth and OIDC endpoints use the standard error and optional error_description fields. Branch on error when the protocol defines it; treat the description as human-readable diagnostic text.
System API validation and business errors usually return JSON containing a message, but the envelope can vary by endpoint and failure type.
Parse JSON case-insensitively, retain unknown fields, and make decisions primarily from the HTTP status and operation context. Messages can be localized or revised; do not compare message text to implement business logic.
Server-Defined Behavior
- Default access-token lifetime is 1 hour and default refresh-token lifetime is 14 days; client-specific values can override them.
- The user list accepts
pageSizeandoffset. Send a positive, bounded page size and a non-negative offset. - Field lengths and required values vary by operation and are documented on the endpoint page.
Do not design a client around undocumented maximums. Use bounded requests, limit concurrency, and apply backoff for transient failures.
Request and Deployment Limits
Payload-size, request-rate, concurrency, and timeout limits can vary by endpoint, deployment, and Guardhouse Cloud plan. A self-hosted operator can also apply stricter limits at a proxy or gateway.
Handle 413, 429, and temporary 503 responses explicitly. Keep payloads reasonably small, honor Retry-After when present, and retry only operations that are safe to repeat.
Guardhouse Cloud Plan Limits
Numeric API-call quotas, user counts, retention, webhook volume, and other commercial entitlements can vary by plan, contract, deployment, or rollout.
Use the limits shown in your Guardhouse Cloud account or contract. If a limit is not shown, contact Guardhouse support rather than copying a number from an SDK default or older document.