Error Codes

Understanding API error responses and how to handle them.

Overview

The API returns standardized error responses with specific error codes to help you identify and resolve issues quickly.

Error Response Format

All error responses follow this structure:

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Missing authentication credentials",
    "details": "Both 'username' and 'password' fields are required",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Field	Type	Description
`status`	string	Always "error" for error responses
`error.code`	string	Unique error identifier
`error.message`	string	Human-readable error message
`error.details`	string	Additional context (optional)
`error.timestamp`	string	ISO 8601 timestamp

Authentication Errors (1000-1099)

Errors related to credentials and authentication.

Code	HTTP	Message	Solution
`AUTH_1001`	401	Missing authentication credentials	Include both username and password in request
`AUTH_1002`	401	Invalid username or password	Verify credentials are correct
`AUTH_1003`	403	Account temporarily locked	Wait before retrying or contact support

Quota Errors (1100-1199)

Errors related to API quota and rate limits.

Code	HTTP	Message	Solution
`QUOTA_1101`	403	Insufficient API quota	Purchase more credits or check quota
`QUOTA_1102`	429	API quota exceeded	Wait for quota reset or upgrade plan

Validation Errors (2000-2099)

Errors related to request validation and input data.

Code	HTTP	Message	Solution
`VAL_2001`	400	No file uploaded	Include a file in the request
`VAL_2002`	400	Invalid file format	Use supported formats: PDF, PNG, JPG, WEBP
`VAL_2003`	400	Multiple PDF files not allowed	Upload single PDF or multiple images
`VAL_2004`	400	PDF and images cannot be mixed	Upload either PDF or images, not both
`VAL_2005`	400	Unsupported language code	Use a supported language code

Processing Errors (3000-3099)

Errors during document processing and AI analysis.

Code	HTTP	Message	Solution
`PROC_3001`	500	Document processing failed	Check image quality, retry request
`PROC_3002`	500	Metadata extraction failed	Ensure document contains readable text
`PROC_3003`	500	Parameters extraction failed	Verify blood test format is recognizable
`PROC_3004`	500	Interpretation generation failed	Retry request
`PROC_3006`	504	Processing timeout	Reduce file size or split into multiple requests
`PROC_3007`	500	Analysis failed after retries	Wait and retry, or contact support

Server Errors (5000-5099)

Internal server errors and service availability issues.

Code	HTTP	Message	Solution
`SRV_5001`	500	Internal server error	Retry request, contact support if persistent
`SRV_5002`	503	Service temporarily unavailable	Wait and retry with exponential backoff

Error Handling Best Practices

Recommendations

Always check the status field - Success responses have "status": "success"
Implement retry logic for transient errors (5xx) with exponential backoff
Log error codes for debugging and monitoring
Display user-friendly messages based on error codes
Use sandbox endpoints to test error handling

Example Error Handling (JavaScript)

async function analyzeBloodTest(file) {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      body: formData
    });

    const data = await response.json();

    if (data.status === 'error') {
      const errorCode = data.error.code;

      switch (true) {
        case errorCode.startsWith('AUTH_'):
          throw new Error('Authentication failed. Please check credentials.');
        case errorCode.startsWith('QUOTA_'):
          throw new Error('Quota exceeded. Please upgrade your plan.');
        case errorCode.startsWith('VAL_'):
          throw new Error('Invalid request: ' + data.error.message);
        case errorCode.startsWith('PROC_'):
          // Retry for processing errors
          return retryRequest(file);
        default:
          throw new Error('An error occurred. Please try again.');
      }
    }

    return data.data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}