Skip to main content

Error Handling

All Gravity Rail API errors return a JSON body with a consistent structure so your integration can reliably parse and act on them.

Response Shape​

4xx Errors​

Client errors return a JSON object with a detail field describing what went wrong:

{"detail": "Resource not found"}

The detail string is safe to display or log — it never contains Protected Health Information (PHI) such as patient names, phone numbers, or message content. See PHI Safety below.

5xx Errors​

Server errors return a fixed generic body regardless of the underlying cause. The actual error is captured in server-side logs and observability tooling, never exposed to the caller:

{"detail": "An internal server error occurred"}

Status Code Reference​

StatusMeaningCommon Causes
400Bad RequestInvalid field value, domain validation failure
401UnauthorizedMissing, expired, or invalid API key / token
403ForbiddenMissing or insufficient permissions for the requested resource
404Not FoundResource does not exist or is not visible to the caller
409ConflictDuplicate resource or a constraint violation (e.g. unique key)
422Unprocessable EntityRequest body or parameters failed schema validation (wrong type, missing required field)
500Internal Server ErrorUnhandled server-side error; retry with exponential back-off

PHI Safety​

Gravity Rail handles Protected Health Information (PHI) in a healthcare context. Error responses are explicitly designed to be safe:

  • 4xx detail strings are sanitized before being sent — they reference record IDs, not patient data.
  • 5xx bodies are always the fixed string above; no exception message, stack trace, or patient data is ever included.
  • Never log the full detail string without review if your system aggregates logs from multiple healthcare workspaces, as workspace-specific IDs may be considered sensitive in your environment.

If you need more context about a server error, include the HTTP response status and any X-Request-Id header in your support request — do not include patient or member data.

Retrying Requests​

  • 400, 401, 403, 404, 409, 422 — do not retry; these require a code, credential, or data fix.
  • 500 — safe to retry with exponential back-off. Transient infrastructure issues typically resolve within seconds.
  • 429 (rate limited) — back off and respect the Retry-After header if present.