<!-- Carebit docs: Validation errors -->

# Validation errors

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

```json
{
  "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:

```json
{
  "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](/guides/support-diagnostics)
for what to attach.