Errors - Guardhouse

Every JSON endpoint returns the same envelope on both success and failure. On success, status.code is 0, errors is empty, and data carries the payload. On failure, the HTTP status reflects the broad failure category and the envelope’s status / errors fields carry detail.

Envelope shape

{
  "status": {
    "code": 100,
    "errorMessage": "Customer 1099 is outside the scope of this API key."
  },
  "data": null,
  "count": null,
  "message": "Customer 1099 is outside the scope of this API key.",
  "errors": [
    {
      "code": 100,
      "message": "Customer 1099 is outside the scope of this API key."
    }
  ]
}

HTTP status codes

Status	Meaning
`200`	Success. Inspect `status.code` for service-level result detail.
`201`	Resource created (used by some webhook subscribe operations).
`400`	Validation failure. The `errors` array names the offending fields.
`401`	Missing, expired, or invalid bearer token. Re-authenticate.
`403`	Authenticated, but the resource is outside your API key’s `KeyType` or `CompanyId`/`CustomerId`/`SiteId` scope.
`404`	Resource does not exist or has been archived.
`429`	Rate limit exceeded (60 requests per minute on external endpoints).
`500`	Unhandled server error. Retry with backoff; if persistent, contact support with the trace ID.

Status codes inside the envelope

status.code is a numeric service-level code that gives more nuance than the HTTP status. The most common values are:

`status.code`	Meaning
`0`	Success.
`100`	Generic application error. Inspect `status.errorMessage` and `errors[]` for detail.
`401`	Authentication required or rejected (mirrors HTTP `401`).
`403`	Authorization failed (mirrors HTTP `403`).
`404`	Resource not found (mirrors HTTP `404`).

The full ServiceResultType catalog evolves over time. For unrecognised codes, fall back to the HTTP status and the errors[].message text — both are stable contracts.

Retry strategy

401 — refresh the bearer token and retry once. Do not retry blindly; if the refresh also fails, the API key has likely been revoked.
403 — do not retry. Fix the request scope.
429 — back off. Honour the next minute boundary; the limit is a fixed window.
5xx — retry with exponential backoff (e.g., 1s, 2s, 4s, 8s) up to a small cap. Treat the request as non-idempotent if you cannot guarantee otherwise.