> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ferrum.thalamiq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Understanding FHIR API error responses

## Error Responses

The FHIR API follows the FHIR specification for error handling, returning `OperationOutcome` resources for errors.

## HTTP Status Codes

The server uses standard HTTP status codes:

* `200 OK` - Successful operation
* `201 Created` - Resource created successfully
* `204 No Content` - Successful deletion or HEAD request
* `400 Bad Request` - Invalid request (malformed syntax, validation errors)
* `401 Unauthorized` - Authentication required
* `403 Forbidden` - Insufficient permissions
* `404 Not Found` - Resource not found
* `405 Method Not Allowed` - HTTP method not supported for endpoint
* `409 Conflict` - Version conflict (e.g., during update)
* `410 Gone` - Resource was deleted
* `412 Precondition Failed` - Conditional operation failed
* `422 Unprocessable Entity` - Business rule violation
* `500 Internal Server Error` - Server error

## OperationOutcome Format

Errors are returned as `OperationOutcome` resources:

```json theme={null}
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Resource validation failed"
      },
      "diagnostics": "Patient.name[0].family: minimum required = 1, but only found 0"
    }
  ]
}
```

## Common Error Scenarios

### Validation Errors (400)

When a resource fails validation:

```json theme={null}
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Required field missing: Patient.name"
      }
    }
  ]
}
```

### Not Found (404)

When a resource doesn't exist:

```json theme={null}
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Resource Patient/123 not found"
      }
    }
  ]
}
```

### Version Conflict (409)

When updating a resource with an outdated version:

```json theme={null}
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "conflict",
      "details": {
        "text": "Version conflict: current version is 2, provided version is 1"
      }
    }
  ]
}
```