Errors

MediLoop uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Code Summary

Status	Name	Description
`200`	OK	Everything worked as expected
`201`	Created	Resource was successfully created
`400`	Bad Request	The request was unacceptable, often due to missing a required parameter
`401`	Unauthorized	No valid API key provided
`403`	Forbidden	The API key doesn't have permissions to perform the request
`404`	Not Found	The requested resource doesn't exist
`409`	Conflict	The request conflicts with another request
`422`	Unprocessable Entity	The request was well-formed but contained semantic errors
`429`	Too Many Requests	Too many requests hit the API too quickly
`500, 502, 503, 504`	Server Errors	Something went wrong on MediLoop's end (these are rare)

Error Response Format

All errors return a JSON object with the following structure:

RESPONSE400

{
  "error": {
    "code": "invalid_request_error",
    "message": "The patient UHID is required",
    "type": "validation_error",
    "param": "uhid",
    "doc_url": "https://docs.mediloop.co/errors/validation_error"
  }
}

Error Attributes

`code` string

A short string indicating the error code reported.

`message` string

A human-readable message providing more details about the error. These messages can be shown to your users.

`type` string

The type of error returned. One of:

api_error - API errors cover any other type of problem
authentication_error - Failure to properly authenticate
invalid_request_error - Invalid request parameters
rate_limit_error - Too many requests
validation_error - Field validation failures

`param` string (optional)

If the error is parameter-specific, the parameter related to the error.

`doc_url` string (optional)

A URL to more information about the error code reported.

Error Types

api_error

API errors cover any other type of problem (e.g., a temporary problem with MediLoop's servers), and are extremely uncommon.

RESPONSE500

{
  "error": {
    "code": "api_error",
    "message": "An unexpected error occurred. Please try again later.",
    "type": "api_error"
  }
}

authentication_error

Authentication errors occur when the API key is invalid, expired, or missing.

RESPONSE401

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided. Check that your API key is correct.",
    "type": "authentication_error"
  }
}

validation_error

Validation errors occur when the request body fails validation.

RESPONSE422

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "type": "validation_error",
    "errors": [
      {
        "field": "date_of_birth",
        "message": "Date of birth cannot be in the future"
      },
      {
        "field": "phone_number",
        "message": "Phone number must be a valid Ugandan number"
      }
    ]
  }
}

Healthcare-Specific Errors

consent_required

Returned when accessing patient data without proper consent.

RESPONSE403

{
  "error": {
    "code": "consent_required",
    "message": "Patient consent is required to access this data",
    "type": "authorization_error",
    "consent_type": "data_access"
  }
}

uhid_not_found

Returned when the specified UHID doesn't exist.

RESPONSE404

{
  "error": {
    "code": "uhid_not_found",
    "message": "No patient found with UHID UG123456789X",
    "type": "not_found_error",
    "param": "uhid"
  }
}

provider_not_verified

Returned when a provider hasn't completed verification.