Error Handling

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

HTTP Status Codes

Status Code	Meaning
200	OK - The request was successful
400	Bad Request - The request was malformed or invalid
401	Unauthorized - Invalid or missing API key
403	Forbidden - Valid API key, but insufficient permissions
404	Not Found - The requested resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end
504	Gateway Timeout - Request took too long to process

Error Response Format

All errors return a JSON object with the following structure:

{
  "error": "Descriptive error message",
  "status": 400
}

Common Errors

Authentication Errors

401: Missing Authorization Header

{
  "error": "Missing Authorization header",
  "status": 401
}

Cause: No Authorization header provided in the request.

Solution: Include the header: Authorization: Bearer YOUR_API_KEY

401: Invalid API Key Format

{
  "error": "Invalid API key format",
  "status": 401
}

Cause: API key doesn't follow the expected format.

Solution: Ensure your API key starts with enh_live_

401: Invalid API Key

{
  "error": "Invalid API key",
  "status": 401
}

Cause: API key is not valid or has been deleted.

Solution: Generate a new API key from your account settings.

Permission Errors

403: Business Plan Required

{
  "error": "API access requires a business plan",
  "status": 403
}

Cause: Your account doesn't have an active business plan.

Solution: Upgrade your account to a business plan at app.enhancv.com

403: Maximum Resume Limit Reached

{
  "error": "Maximum resume limit reached",
  "status": 403
}

Cause: You've reached the maximum number of resumes allowed on your plan.

Solution: Delete unused resumes or upgrade your plan for more storage.

Validation Errors

400: No File Uploaded

{
  "error": "No file uploaded",
  "status": 400
}

Cause: Upload request doesn't include a file.

Solution: Ensure your form data includes a file field with the resume file.

400: File Size Exceeds Limit

{
  "error": "File size exceeds 10MB",
  "status": 400
}

Cause: Uploaded file is larger than 10MB.

Solution: Compress or resize the file before uploading.

400: Invalid File Type

{
  "error": "Invalid file type. Only PDF, DOC, and DOCX are allowed",
  "status": 400
}

Cause: File format is not supported.

Solution: Convert the file to PDF, DOC, or DOCX format.

400: Invalid Format Parameter

{
  "error": "Invalid format. Must be 'pdf' or 'txt'",
  "status": 400
}

Cause: The format query parameter is not valid.

Solution: Use format=pdf or format=txt

Resource Errors

404: Resume Not Found

{
  "error": "Resume not found",
  "status": 404
}

Cause: Resume ID doesn't exist or doesn't belong to your account.

Solution: Verify the resume ID using the List Resumes endpoint.

Rate Limit Errors

429: Rate Limit Exceeded

{
  "error": "Rate limit exceeded. Please try again later.",
  "status": 429,
  "retryAfter": 30
}

Cause: You've exceeded the rate limit for your plan.

Solution: Wait for the time specified in retryAfter (seconds) before retrying.

Server Errors

500: Internal Server Error

{
  "error": "Internal server error",
  "status": 500
}

Cause: Unexpected error on our servers.

Solution: Retry the request. If the problem persists, contact support.

504: Gateway Timeout

{
  "error": "PDF generation timeout. Please try again later.",
  "status": 504
}

Cause: Request took too long to process (usually PDF generation).

Solution: Retry the request. PDF generation usually completes in 5-10 seconds.

Error Handling Examples

JavaScript

async function handleAPIRequest(url, options) {
  try {
    const response = await fetch(url, options);

    // Check if response is ok
    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 401:
          console.error('Authentication failed:', error.error);
          // Redirect to login or show error
          break;

        case 403:
          console.error('Permission denied:', error.error);
          // Show upgrade prompt if business plan required
          break;

        case 404:
          console.error('Resource not found:', error.error);
          break;

        case 429:
          console.log(`Rate limited. Retry after ${error.retryAfter}s`);
          // Implement retry logic
          break;

        case 500:
          console.error('Server error:', error.error);
          // Show generic error message
          break;

        default:
          console.error('API error:', error.error);
      }

      throw new Error(error.error);
    }

    return await response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

Python

import requests
import time

def handle_api_request(url, headers):
    try:
        response = requests.get(url, headers=headers)

        # Raise exception for error status codes
        if not response.ok:
            error_data = response.json()
            error_message = error_data.get('error', 'Unknown error')

            if response.status_code == 401:
                raise Exception(f"Authentication failed: {error_message}")

            elif response.status_code == 403:
                raise Exception(f"Permission denied: {error_message}")

            elif response.status_code == 404:
                raise Exception(f"Resource not found: {error_message}")

            elif response.status_code == 429:
                retry_after = error_data.get('retryAfter', 60)
                print(f"Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                # Retry the request
                return handle_api_request(url, headers)

            elif response.status_code >= 500:
                raise Exception(f"Server error: {error_message}")

            else:
                raise Exception(f"API error: {error_message}")

        return response.json()

    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        raise

Best Practices

1. Always Check Response Status

Don't assume requests succeed. Always check the status code:

const response = await fetch(url, options);

if (!response.ok) {
  // Handle error
  const error = await response.json();
  console.error('API Error:', error);
}

2. Implement Retry Logic

For transient errors (429, 500, 504), implement retry with exponential backoff:

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

3. Log Errors for Debugging

Log errors with context to help debugging:

console.error('API Error:', {
  url: request.url,
  method: request.method,
  status: error.status,
  message: error.error,
  timestamp: new Date().toISOString()
});

4. Show User-Friendly Messages

Don't expose raw error messages to end users:

const userMessages = {
  401: 'Please check your API credentials.',
  403: 'You don\'t have permission to perform this action.',
  404: 'The requested resume was not found.',
  429: 'Too many requests. Please try again in a moment.',
  500: 'Something went wrong. Please try again later.'
};

const message = userMessages[error.status] || 'An unexpected error occurred.';
showToUser(message);

Need Help?

If you encounter errors you can't resolve:

1. Check this documentation for solutions
2. Verify your API key is valid
3. Ensure your account has an active business plan
4. Contact support at support@enhancv.com with:
   • Error message
   • Request details (endpoint, method, parameters)
   • Timestamp of the error