Error Handling

Understanding and handling API errors in HealthTalk.

Error Response Format

All errors return a consistent JSON structure:


{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is missing required field 'patientId'",
    "details": {
      "field": "patientId",
      "reason": "required"
    }
  }
}

HTTP Status Codes

Status	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource already exists
422	Unprocessable - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Error Codes

Authentication Errors

Code	Description
`INVALID_SIGNATURE`	HMAC signature verification failed
`EXPIRED_TIMESTAMP`	Request timestamp too old
`INVALID_TENANT`	Tenant ID not recognized

Validation Errors

Code	Description
`INVALID_REQUEST`	Request body malformed
`MISSING_FIELD`	Required field not provided
`INVALID_FORMAT`	Field format incorrect

Resource Errors

Code	Description
`PATIENT_NOT_FOUND`	Patient ID doesn’t exist
`TEMPLATE_NOT_FOUND`	Template ID doesn’t exist
`MESSAGE_NOT_FOUND`	Message ID doesn’t exist

Best Practices

Always check HTTP status codes
Log error details for debugging
Implement exponential backoff for retries
Handle rate limits gracefully