Skip to main content

​
HTTP Status Codes

CodeMeaningDescription
200SuccessRequest completed successfully
400Bad RequestInvalid request parameters or format
401UnauthorizedMissing or invalid authentication
404Not FoundFile or resource doesn’t exist
409ConflictFile already exists (write operation)
422Unprocessable EntityBusiness rule violation
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error

​
Error Response Format

All errors return a consistent JSON structure: 
{
  "success": false,
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File not found at path: documents/report.pdf"
  },
  "operation": "read_file",
  "details": {
    "path": "documents/report.pdf",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

​
Common Error Codes

​
Authentication Errors

HTTP 401 - API key is missing, malformed, or invalidSolution:
  • Verify your API key starts with oa_
  • Check for extra spaces or characters
  • Regenerate key if compromised
HTTP 429 - Too many requests in time windowSolution:
  • Implement exponential backoff
  • Check X-RateLimit-Reset header
  • Upgrade tier for higher limits

​
File Operation Errors

HTTP 404 - Requested file doesn’t existSolution:
  • Verify file path (no leading slashes)
  • Use list_files to check available files
  • Ensure file was created successfully
HTTP 409 - File exists, use edit/overwrite insteadSolution:
  • Use edit_file for partial updates
  • Use overwrite_file to replace content
  • Add version parameter to create new version
HTTP 400 - File path format is invalidSolution:
  • Use forward slashes: folder/file.txt
  • No leading slashes: folder/file.txt not /folder/file.txt
  • Avoid special characters in paths
HTTP 413 - File exceeds size limitsSolution:
  • Check tier limits (Free: 10MB, Pro: 100MB)
  • Break large files into chunks
  • Consider upgrading for larger limits
HTTP 422 - String to replace not found in fileSolution:
  • Verify exact string match (case-sensitive)
  • Check for invisible characters or encoding
  • Use read_file to see current content

​
Error Handling Best Practices

​
Retry Logic

Implement exponential backoff for transient errors: 
async function apiCallWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await apiCall()
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.min(1000 * Math.pow(2, attempt), 30000)
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }
      throw error // Don't retry client errors
    }
  }
  throw new Error('Max retries exceeded')
}

​
Logging and Monitoring

Track error patterns to improve reliability: 
function logApiError(error, operation, context) {
  console.error('OpenFiles API Error', {
    operation,
    errorCode: error.error?.code,
    message: error.error?.message,
    statusCode: error.status,
    context,
    timestamp: new Date().toISOString()
  })
  
  // Send to monitoring service
  if (error.status >= 500) {
    monitoring.reportServerError(error)
  }
}

​
Getting Help

If you encounter persistent errors:

Check API Status

Visit status.openfiles.ai for service status

Email Support

Contact our team at support@openfiles.ai
⌘I