​

Error Handling

​

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