API reference / Errors

Every error code, in one place

Every HyperCRM API response, success or failure, follows one of two envelope shapes, with the few exceptions listed below. This page lists both shapes, how request ids work, and the full table of error codes and HTTP statuses an endpoint can return.

The two envelopes

Every HyperCRM API response follows one of two envelope shapes, with these exceptions: the OAuth endpoints /api/v1/oauth/token, /api/v1/oauth/register and /api/v1/oauth/revoke use the standard OAuth body (error, error_description); a CSV export returns a file; GET /api/v1/files/{fileId}/content is a 302 to the stored file; /api/v1/openapi.json is the specification document itself; and the MCP endpoint speaks JSON-RPC rather than REST.

Successful responses (2xx) always look like this, with data holding the resource and requestId for correlation:

{
  "data": { "...": "resource-specific shape" },
  "requestId": "req_5f2c1e40-..."
}

POST endpoints that create a resource return 201 with the same shape. Error responses (4xx/5xx) share the mirror shape, with a stable code, a safe-to-display message, the same requestId, and an optional details array. Each entry has a message and may have a path, a field and a machine-readable code (for example invalid_json, or chair_booked on a booking conflict):

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "requestId": "req_5f2c1e40-...",
    "details": [ { "path": ["firstName"], "message": "firstName is required" } ]
  }
}

The detail object

Separately from the details array, a refusal that a client can act on carries a detail object holding the machine-readable reason, for example detail.feature on a plan refusal or detail.limit and detail.used on a cap. The keys in use are feature, resource, limit, used, requiredPlan, cost, remaining, resetsAt, reason, since, practiceName and practiceLogoUrl. Read the keys you know by name rather than switching on the whole set: more are added as new refusals need them, and an unknown one should be ignored rather than treated as an error.

Rate-limit headers

A 429 carries Retry-After in seconds, never below 1, together with RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). A successful response carries none of these, so read the budget from the 429 you already have to handle. Per minute, REST allows 300 requests per user, 120 of them writes, and 600 per IP address; the MCP endpoint allows 120 per access token.

The OAuth endpoints are different

/api/v1/oauth/token, /api/v1/oauth/register and /api/v1/oauth/revoke answer in the OAuth grammar instead of the envelope above: error and error_description, with the status in the response line. The codes are the registered OAuth ones, so a standard client library already understands them: invalid_request, invalid_client, invalid_grant, unsupported_grant_type and invalid_target (400), server_error for anything 5xx, and temporarily_unavailable for a throttled request, which keeps the 429 status so a client that only knows the OAuth list still backs off correctly.

Request ids

Every JSON response carries an x-request-id header, and the same value appears as requestId in the body. A CSV download and a redirect to file content carry neither. If the incoming request supplies its own x-request-id (or x-correlation-id) header matching a safe pattern, that value is echoed back for client-side log correlation; otherwise the server generates one of the form req_<uuid>.

Back to the API reference hub for the other resource pages.