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

# API error codes and troubleshooting reference

> Full reference of OMOPHub API error codes and HTTP statuses with guidance on how to troubleshoot 4xx and 5xx responses in your integration.

# Error Handling

OMOPHub API uses conventional HTTP response codes and provides detailed error information.

## HTTP Status Codes

### Success Codes

* `200 OK` - Request successful
* `201 Created` - Resource created successfully
* `204 No Content` - Request successful, no content to return

### Client Error Codes (4xx)

* `400 Bad Request` - Invalid request parameters
* `401 Unauthorized` - Authentication required
* `403 Forbidden` - Insufficient permissions
* `404 Not Found` - Resource not found
* `413 Payload Too Large` - Request body exceeds size limits
* `422 Unprocessable Entity` - Valid request format but semantic errors
* `429 Too Many Requests` - Rate limit exceeded

### Server Error Codes (5xx)

* `500 Internal Server Error` - Unexpected server error
* `503 Service Unavailable` - Service temporarily unavailable

## Common Error Codes

### Authentication & Authorization

* `missing_api_key` (401) - No API key provided in Authorization header
* `invalid_api_key` (403) - API key is invalid, expired, or revoked
* `unauthorized` (401) - Authentication token is invalid
* `forbidden` (403) - Insufficient permissions for this resource

### Request Validation

* `validation_error` (422) - Well-formed request but semantically invalid parameters
* `missing_required_field` (400) - Required fields missing or malformed in the request
* `bad_request` (400) - General malformed request (bad JSON/format)

### Resource Management

* `not_found` (404) - Requested resource does not exist
* `concept_not_found` (404) - Specific concept ID not found
* `vocabulary_not_found` (404) - Vocabulary ID not found

### Rate Limits & Quotas

* `rate_limit_exceeded` (429) - Too many requests per second
* `daily_quota_exceeded` (429) - Daily request limit reached

### Healthcare & Security

* `healthcare_data_error` (422) - Medical data validation failure
* `invalid_mapping` (400) - Concept mapping validation error

### System & Service Errors

* `internal_server_error` (500) - Unexpected server error
* `service_unavailable` (503) - API temporarily unavailable

### Version & Compatibility

* `version_not_supported` (400) - Requested API version not supported
* `search_error` (400) - Search operation failed