Validation errors

Every error response is a JSON object with an error envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_reused",
    "message": "This `Idempotency-Key` was already used for a different request."
  }
}

The type groups errors by category and the code is a stable machine identifier. Do not rely on message for logic; localize display strings in your frontend and switch on code.

Status codes

Status	Meaning
`400`	Malformed request. Missing headers, unparseable body, invalid encoding.
`401`	Missing, expired, or invalid access token.
`403`	Access token does not carry the scope this endpoint requires.
`404`	Resource does not exist or is out of the caller's Organization.
`409`	Domain conflict, for example an `Idempotency-Key` in flight.
`422`	Semantic validation failure (invalid enum, missing required field).
`429`	Rate limit hit. Retry after `Retry-After` seconds.
`5xx`	Retryable server error.

Field-level errors

Semantic 422 responses list every offending field:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "`patient_id` is required.",
    "param": "patient_id",
    "errors": [
      {
        "code": "missing_parameter",
        "message": "`patient_id` is required.",
        "param": "patient_id"
      },
      {
        "code": "missing_parameter",
        "message": "`start_time` is required.",
        "param": "start_time"
      }
    ]
  }
}

The first validation error is promoted to error.code, error.message, and error.param. Every entry in error.errors uses the same stable code, message, and param shape.

Request ID

Every response includes a Carebit-Developer-Platform-API-Request-Id header. Include it in every support ticket and log it alongside your own correlation IDs. See Support diagnostics for what to attach.